# GLINUI full documentation

> 142 components concatenated. Size: about 714 KB (roughly 183k tokens). For one component, fetch https://glinui.com/md/<id>.md instead.

---

# Button

> Action control with default, glass, liquid, matte, glow, outline, and ghost variants.

- id: `button`
- type: primitive
- category: Buttons
- tags: primitive
- docs: https://glinui.com/docs/components/radix/button
- markdown: https://glinui.com/md/button.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add button
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/button.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Button, SURFACE_VARIANTS, SURFACE_TONES, SURFACE_ELEVATIONS, SURFACE_VARIANT_ALIASES, STYLE_DEFAULT_VARIANT, GlinProvider, GLIN_MOTIONS } from "@glinui/ui"
```

## Usage

An editor action bar: a destructive soft button, a ghost cancel and a solid save that shows its loading state.

```tsx
"use client"

import { useEffect, useRef, useState } from "react"
import { Check, FloppyDisk, Trash } from "@phosphor-icons/react"
import { Badge, Button, Card, CardDescription, CardFooter, CardHeader, CardTitle } from "@glinui/ui"

export function ButtonActionBar() {
  const [state, setState] = useState<"idle" | "saving" | "saved">("idle")
  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
  useEffect(() => () => clearTimeout(timer.current), [])

  function save() {
    setState("saving")
    timer.current = setTimeout(() => setState("saved"), 1400)
  }

  return (
    <Card className="w-full max-w-xl">
      <CardHeader>
        <div className="flex items-center justify-between gap-3">
          <CardTitle>Release notes for v2.4</CardTitle>
          <Badge tone={state === "saved" ? "success" : "warning"} variant="soft" dot>
            {state === "saved" ? "Saved" : "Unsaved changes"}
          </Badge>
        </div>
        <CardDescription>Edited a few minutes ago by Maya Chen. Changes apply to the public changelog.</CardDescription>
      </CardHeader>
      <CardFooter className="flex flex-wrap items-center justify-between gap-3">
        <Button variant="soft" tone="danger" leadingIcon={<Trash weight="bold" />}>
          Delete draft
        </Button>
        <div className="flex items-center gap-2">
          <Button variant="ghost" onClick={() => setState("idle")}>
            Cancel
          </Button>
          <Button
            variant="solid"
            tone="accent"
            loading={state === "saving"}
            leadingIcon={state === "saved" ? <Check weight="bold" /> : <FloppyDisk weight="bold" />}
            onClick={save}
          >
            {state === "saving" ? "Saving" : state === "saved" ? "Saved" : "Save changes"}
          </Button>
        </div>
      </CardFooter>
    </Card>
  )
}
```

### Variants

```tsx
import { Button, SURFACE_TONES, SURFACE_VARIANTS } from "@glinui/ui"

export function Demo() {
  return (
    <div className="grid gap-2">
      {SURFACE_VARIANTS.map((variant) => (
        <div key={variant} className="flex flex-wrap gap-2">
          {SURFACE_TONES.map((tone) => (
            <Button key={tone} variant={variant} tone={tone}>
              {variant} {tone}
            </Button>
          ))}
        </div>
      ))}
    </div>
  )
}
```

### Glass (opt-in)

```tsx
import { Button } from "@glinui/ui"

// Glass needs a colorful or photographic backdrop to read.
export function Demo() {
  return <Button variant="glass">Glass</Button>
}
```

## Props

### ButtonProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `asChild?` | `boolean` | `false` |  |
| `iconNudge?` | `boolean` |  |  |
| `leadingIcon?` | `React.ReactNode` |  | Icon before the label (decorative). |
| `loading?` | `boolean` | `false` | Show a spinner, set `aria-busy` and block interaction. |
| `size?` | `ButtonSize` |  |  |
| `tone?` | `ButtonTone` |  | Colour axis for the vocabulary variants. |
| `trailingIcon?` | `React.ReactNode` |  | Icon after the label (decorative). |
| `variant?` | `ButtonVariant` |  | Look. Omit for the ambient default (`glinr`, or `plain` / `glass` under `style="minimal"` / `"glass"`). Legacy names (`default`, `primary... |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Native `button` semantics by default.
- Visible 2px accent focus ring with offset on every variant (plain uses a neutral ring).
- `disabled` and `loading` block interaction, lower emphasis and set `aria-disabled` / `aria-busy`.
- Icon-only buttons need an `aria-label`.
- Supports `asChild` for semantic link rendering.

Keyboard:

| Key | Action |
| --- | --- |
| Enter | Activate the button. |
| Space | Activate the button. |

ARIA:

- `role="button"` native
- `aria-disabled` when disabled or loading
- `aria-busy` while loading

- Reduced motion: Transitions use tokenized timing and disable transform-heavy motion with `prefers-reduced-motion`.

---

# Shimmer Button

> Button with animated shimmer sweep overlay and glass-aware variants.

- id: `shimmer-button`
- type: signature
- category: Buttons
- tags: signature
- docs: https://glinui.com/docs/components/shimmer-button
- markdown: https://glinui.com/md/shimmer-button.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add shimmer-button
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/shimmer-button.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { ShimmerButton, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider } from "@glinui/ui"
```

## Usage

```tsx
import { ShimmerButton } from "@glinui/ui"

export function ShimmerButtonVariantsDemo() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <ShimmerButton variant="glinr">glinr</ShimmerButton>
      <ShimmerButton variant="solid">solid</ShimmerButton>
      <ShimmerButton variant="plain">plain</ShimmerButton>
      <ShimmerButton variant="soft">soft</ShimmerButton>
      <ShimmerButton variant="outline">outline</ShimmerButton>
      <ShimmerButton variant="ghost">ghost</ShimmerButton>
      <ShimmerButton variant="gradient">gradient</ShimmerButton>
    </div>
  )
}
```

```tsx
import { ShimmerButton } from "@glinui/ui"

export function ShimmerButtonGlassDemo() {
  return (
    <ShimmerButton variant="glass">Glass</ShimmerButton>
  )
}
```

```tsx
import { ShimmerButton } from "@glinui/ui"

export function ShimmerButtonSizesDemo() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <ShimmerButton size="sm">SM</ShimmerButton>
      <ShimmerButton size="md">MD</ShimmerButton>
      <ShimmerButton size="lg">LG</ShimmerButton>
    </div>
  )
}
```

## Props

### ShimmerButtonProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `shimmerColor?` | `string` |  | Sweep colour. Defaults to the button's own text colour at 35 percent, so it shows on light and dark surfaces. |
| `shimmerDuration?` | `number` | `2` | Seconds per sweep. |
| `variant?` | `ButtonVariant \| "accent"` |  | Vocabulary or legacy variant. `accent` is kept as an alias of `primary`. Omit for the ambient default. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `accent`.

## Accessibility

- Renders through `Button`: native ``, 2px accent focus ring with offset, `disabled` and `aria-busy` states.
- Accessible name comes from the label. Decorative effect layers are `aria-hidden` and `pointer-events-none`.
- Reduced motion: The sweep renders only at motion level `full`. It is removed under `prefers-reduced-motion` and `data-glin-motion="none"`, leaving a normal button.

---

# Ripple Button

> Button with liquid ripple effect on press.

- id: `ripple-button`
- type: signature
- category: Buttons
- tags: signature
- docs: https://glinui.com/docs/components/ripple-button
- markdown: https://glinui.com/md/ripple-button.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add ripple-button
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/ripple-button.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { RippleButton, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider } from "@glinui/ui"
```

## Usage

```tsx
import { RippleButton } from "@glinui/ui"

export function RippleButtonVariantsDemo() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <RippleButton variant="glinr">glinr</RippleButton>
      <RippleButton variant="solid">solid</RippleButton>
      <RippleButton variant="plain">plain</RippleButton>
      <RippleButton variant="soft">soft</RippleButton>
      <RippleButton variant="outline">outline</RippleButton>
      <RippleButton variant="ghost">ghost</RippleButton>
      <RippleButton variant="gradient">gradient</RippleButton>
    </div>
  )
}
```

```tsx
import { RippleButton } from "@glinui/ui"

export function RippleButtonGlassDemo() {
  return (
    <RippleButton variant="glass">Glass</RippleButton>
  )
}
```

```tsx
import { RippleButton } from "@glinui/ui"

export function RippleButtonSizesDemo() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <RippleButton size="sm">SM</RippleButton>
      <RippleButton size="md">MD</RippleButton>
      <RippleButton size="lg">LG</RippleButton>
    </div>
  )
}
```

## Props

### RippleButtonProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `rippleColor?` | `string` |  | Ripple colour. Defaults to the button's own text colour at 30 percent, so it shows on light and dark surfaces. |
| `variant?` | `ButtonVariant` |  | Vocabulary or legacy variant. Omit for the ambient default. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Renders through `Button`: native ``, 2px accent focus ring with offset, `disabled` and `aria-busy` states.
- Accessible name comes from the label. Decorative effect layers are `aria-hidden` and `pointer-events-none`.
- Defaults to `type="button"`.
- Reduced motion: No ripple is created under `prefers-reduced-motion` or `data-glin-motion="none"`. The click handler still runs.

---

# Pulsating Button

> Button with a pulsing glow ring animation for attention-grabbing CTAs.

- id: `pulsating-button`
- type: signature
- category: Buttons
- tags: signature
- docs: https://glinui.com/docs/components/pulsating-button
- markdown: https://glinui.com/md/pulsating-button.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add pulsating-button
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/pulsating-button.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { PulsatingButton, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider } from "@glinui/ui"
```

## Usage

```tsx
import { PulsatingButton } from "@glinui/ui"

export function PulsatingButtonVariantsDemo() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <PulsatingButton variant="glinr">glinr</PulsatingButton>
      <PulsatingButton variant="solid">solid</PulsatingButton>
      <PulsatingButton variant="plain">plain</PulsatingButton>
      <PulsatingButton variant="soft">soft</PulsatingButton>
      <PulsatingButton variant="outline">outline</PulsatingButton>
      <PulsatingButton variant="ghost">ghost</PulsatingButton>
      <PulsatingButton variant="gradient">gradient</PulsatingButton>
    </div>
  )
}
```

```tsx
import { PulsatingButton } from "@glinui/ui"

export function PulsatingButtonGlassDemo() {
  return (
    <PulsatingButton variant="glass">Glass</PulsatingButton>
  )
}
```

```tsx
import { PulsatingButton } from "@glinui/ui"

export function PulsatingButtonColorDemo() {
  return (
    <PulsatingButton pulseColor="var(--tone-success)" pulseDuration={1.5}>
      Custom pulse
    </PulsatingButton>
  )
}
```

## Props

### PulsatingButtonProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `pulseColor?` | `string` |  | Ring colour. Defaults to the accent token, visible on light and dark scopes. |
| `pulseDuration?` | `number` | `2` | Seconds per pulse. |
| `variant?` | `ButtonVariant \| "accent"` |  | Vocabulary or legacy variant. `accent` is kept as an alias of `primary`. Omit for the ambient default. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `accent`.

## Accessibility

- Renders through `Button`: native ``, 2px accent focus ring with offset, `disabled` and `aria-busy` states.
- Accessible name comes from the label. Decorative effect layers are `aria-hidden` and `pointer-events-none`.
- Reduced motion: The ring renders only at motion level `full`. It is removed under `prefers-reduced-motion` and `data-glin-motion="none"`.

---

# Liquid Button

> Button with fluid hover lift, press squish, and radial shine effect.

- id: `liquid-button`
- type: signature
- category: Buttons
- tags: signature
- docs: https://glinui.com/docs/components/liquid-button
- markdown: https://glinui.com/md/liquid-button.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add liquid-button
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/liquid-button.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { LiquidButton } from "@glinui/ui"
```

## Usage

```tsx
import { LiquidButton } from "@glinui/ui"

export function LiquidButtonVariantsDemo() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <LiquidButton variant="glinr">glinr</LiquidButton>
      <LiquidButton variant="solid">solid</LiquidButton>
      <LiquidButton variant="plain">plain</LiquidButton>
      <LiquidButton variant="soft">soft</LiquidButton>
      <LiquidButton variant="outline">outline</LiquidButton>
      <LiquidButton variant="ghost">ghost</LiquidButton>
      <LiquidButton variant="gradient">gradient</LiquidButton>
    </div>
  )
}
```

```tsx
import { LiquidButton } from "@glinui/ui"

export function LiquidButtonGlassDemo() {
  return (
    <LiquidButton variant="glass">Glass</LiquidButton>
  )
}
```

```tsx
import { LiquidButton } from "@glinui/ui"

export function LiquidButtonIntensityDemo() {
  return (
    <div className="flex flex-wrap gap-3">
      <LiquidButton intensity="soft">Soft</LiquidButton>
      <LiquidButton intensity="strong">Strong</LiquidButton>
    </div>
  )
}
```

## Props

### LiquidButtonProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `intensity?` | `"soft" \| "strong"` | `"soft"` | Variant option from liquidButtonVariants. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Renders through `Button`: native ``, 2px accent focus ring with offset, `disabled` and `aria-busy` states.
- Accessible name comes from the label. Decorative effect layers are `aria-hidden` and `pointer-events-none`.
- Reduced motion: Scale, brightness and the fill transition are disabled under `prefers-reduced-motion` and `data-glin-motion="none"`.

---

# Magnetic CTA

> Call-to-action button with subtle cursor-attraction on hover.

- id: `magnetic-cta`
- type: signature
- category: Buttons
- tags: signature
- docs: https://glinui.com/docs/components/magnetic-cta
- markdown: https://glinui.com/md/magnetic-cta.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add magnetic-cta
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/magnetic-cta.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { MagneticCTA, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider } from "@glinui/ui"
```

## Usage

```tsx
import { MagneticCTA } from "@glinui/ui"

export function MagneticCTAVariantsDemo() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <MagneticCTA variant="glinr">glinr</MagneticCTA>
      <MagneticCTA variant="solid">solid</MagneticCTA>
      <MagneticCTA variant="plain">plain</MagneticCTA>
      <MagneticCTA variant="soft">soft</MagneticCTA>
      <MagneticCTA variant="outline">outline</MagneticCTA>
      <MagneticCTA variant="ghost">ghost</MagneticCTA>
      <MagneticCTA variant="gradient">gradient</MagneticCTA>
    </div>
  )
}
```

```tsx
import { MagneticCTA } from "@glinui/ui"

export function MagneticCTAGlassDemo() {
  return (
    <MagneticCTA variant="glass">Glass</MagneticCTA>
  )
}
```

```tsx
import { MagneticCTA } from "@glinui/ui"

export function MagneticCTAStrongDemo() {
  return (
    <div className="flex flex-wrap gap-6">
      <MagneticCTA variant="solid" maxOffset={14} magnetRadius={180}>
        Strong pull
      </MagneticCTA>
      <MagneticCTA variant="outline" maxOffset={4} magnetRadius={80}>
        Subtle pull
      </MagneticCTA>
    </div>
  )
}
```

## Props

### MagneticCTAProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `containerClassName?` | `string` |  |  |
| `magnetRadius?` | `number` | `140` |  |
| `maxOffset?` | `number` | `8` |  |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Renders through `Button`: native ``, 2px accent focus ring with offset, `disabled` and `aria-busy` states.
- Accessible name comes from the label. Decorative effect layers are `aria-hidden` and `pointer-events-none`.
- The focus ring stays on the button and is not hidden by the offset.
- Reduced motion: The pull is disabled under `prefers-reduced-motion` and `data-glin-motion="none"`: the offset resets to zero.

---

# Interactive Hover Button

> Pill button whose accent dot floods the surface on hover, focus or press.

- id: `interactive-hover-button`
- type: primitive
- category: Buttons
- tags: primitive, adapted
- docs: https://glinui.com/docs/components/radix/interactive-hover-button
- markdown: https://glinui.com/md/interactive-hover-button.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add interactive-hover-button
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/interactive-hover-button.json
```

Package:

```bash
npm install @glinui/ui @glinui/motion @glinui/tokens
```

## Import

```tsx
import { InteractiveHoverButton, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider } from "@glinui/ui"
```

## Usage

Adapted from Interactive Hover Button by Magic UI (MIT).

Improvements: one accessible label instead of two, a cheap clip-path fill instead of a 100x scaled dot, focus-visible and active parity with hover, logical RTL offsets with a mirrored arrow, sizes, the shared variant vocabulary (glinr default, glass opt-in), loading, asChild and motion levels.

Hover, focus or press the button to flood it with the accent.

```tsx
import { Card, CardDescription, CardFooter, CardHeader, CardTitle, InteractiveHoverButton } from "@glinui/ui"

export function HoverButtonCta() {
  return (
    <Card className="w-full max-w-md">
      <CardHeader>
        <CardTitle>Join the beta</CardTitle>
        <CardDescription>Early access to the new analytics workspace. Hover or focus the button to see it fill.</CardDescription>
      </CardHeader>
      <CardFooter className="flex flex-wrap items-center justify-between gap-3">
        <span className="text-sm text-[var(--color-muted)]">1,240 teams already in</span>
        <InteractiveHoverButton>Request access</InteractiveHoverButton>
      </CardFooter>
    </Card>
  )
}
```

### Variants

The shared vocabulary. The accent dot floods whichever surface you pick.

```tsx
<div className="flex flex-wrap items-center gap-3">
<InteractiveHoverButton variant="glinr">glinr</InteractiveHoverButton>
<InteractiveHoverButton variant="solid">solid</InteractiveHoverButton>
<InteractiveHoverButton variant="plain">plain</InteractiveHoverButton>
<InteractiveHoverButton variant="soft">soft</InteractiveHoverButton>
<InteractiveHoverButton variant="outline">outline</InteractiveHoverButton>
<InteractiveHoverButton variant="ghost">ghost</InteractiveHoverButton>
<InteractiveHoverButton variant="gradient">gradient</InteractiveHoverButton>
</div>
```

### Glass (opt-in)

Glass is never the default. It needs a colorful or photographic backdrop to read.

```tsx
<InteractiveHoverButton variant="glass">Book a demo</InteractiveHoverButton>
```

## Props

### InteractiveHoverButtonProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `leadingIcon?` | `React.ReactNode` |  | Icon before the label (decorative). |
| `loading?` | `boolean` | `false` | Show a spinner, set aria-busy and block interaction. |
| `size?` | `"xs" \| "sm" \| "md" \| "lg" \| "icon"` | `"md"` | Variant option from interactiveHoverButtonVariants. |
| `trailingIcon?` | `React.ReactNode` |  | Icon after the label. Defaults to an arrow that mirrors in RTL on the hover face. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Native button (or your element with asChild) with the Button focus ring.
- The hover face is aria-hidden, so the label is read once. The original duplicated it.
- Keyboard focus triggers the same fill as hover, and press fills it on touch.

Keyboard:

| Key | Action |
| --- | --- |
| Enter | Activates the button. |
| Space | Activates the button. |
| Tab | Moves focus and plays the fill. |

ARIA:

- `aria-busy` while loading
- `aria-disabled` when disabled or loading
- Decorative icons and the hover face use `aria-hidden`

- Reduced motion: Motion level full slides the label and floods the surface with a clip-path. Subtle keeps the flood and opacity swap but drops the slide. None, or prefers-reduced-motion, switches state instantly. Hover effects only run on fine pointers.

## Provenance

Adapted from Magic UI (MIT, Copyright (c) Magic UI). Upstream: https://magicui.design/docs/components/interactive-hover-button. Restyled to Glin tokens with accessibility and reduced motion review. Keep the attribution when you copy this component.

---

# Generate Button

> AI style call to action with idle, generating and loading states.

- id: `generate-button`
- type: primitive
- category: Buttons
- tags: primitive, adapted
- docs: https://glinui.com/docs/components/radix/generate-button
- markdown: https://glinui.com/md/generate-button.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add generate-button
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/generate-button.json
```

Package:

```bash
npm install @glinui/ui @glinui/motion @glinui/tokens
```

## Import

```tsx
import { GenerateButton, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider, GlinProvider, SURFACE_VARIANTS, SURFACE_TONES, SURFACE_ELEVATIONS } from "@glinui/ui"
```

## Usage

Adapted from Generate Button by Ashutoshx7 (Vengeance UI, MIT).

Improvements: no injected style tag or font stack, scoped utilities on tokens, explicit generating and loading props instead of focus-driven state, aria-busy with a polite announcement, real disabled state, variant vocabulary (glinr default, glass opt-in), sizes and asChild.

Click to enter the glowing generating state, click again to stop.

```tsx
import { Sparkle } from "@phosphor-icons/react"
import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, GenerateButton } from "@glinui/ui"

export function GenerateCompose() {
  return (
    <Card className="w-full max-w-md">
      <CardHeader>
        <CardTitle>Product description</CardTitle>
        <CardDescription>Draft copy for the Studio keyboard from its spec sheet. Press the button to start and again to stop.</CardDescription>
      </CardHeader>
      <CardContent>
        <div className="rounded-lg border border-border/60 p-3 text-sm text-[var(--color-muted)]">
          75% layout, gasket mount, hot-swap switches, USB-C and Bluetooth, aluminum case in three finishes.
        </div>
      </CardContent>
      <CardFooter className="flex items-center justify-between gap-3">
        <span className="text-sm text-[var(--color-muted)]">Uses 1 credit</span>
        <GenerateButton label="Generate copy" generatingLabel="Writing" leadingIcon={<Sparkle weight="fill" />} />
      </CardFooter>
    </Card>
  )
}
```

### Variants

The shining label follows the surface text colour on every variant.

```tsx
<div className="flex flex-wrap items-center gap-3">
<GenerateButton variant="glinr" label="glinr" />
<GenerateButton variant="solid" label="solid" />
<GenerateButton variant="plain" label="plain" />
<GenerateButton variant="soft" label="soft" />
<GenerateButton variant="outline" label="outline" />
<GenerateButton variant="ghost" label="ghost" />
<GenerateButton variant="gradient" label="gradient" />
</div>
```

### Glass (opt-in)

Glass is never the default. It needs a colorful or photographic backdrop to read.

```tsx
<GenerateButton variant="glass" defaultGenerating label="Draft reply" generatingLabel="Drafting" />
```

## Props

### GenerateButtonProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children?` | `React.ReactElement` |  | With `asChild`, pass the element to render, for example an anchor. |
| `defaultGenerating?` | `boolean` | `false` | Initial generating state when uncontrolled. |
| `generatingLabel?` | `string` | `"Generating"` | Label shown (and announced) while generating. |
| `hue?` | `number` |  | Highlight hue, 0 to 360. Defaults to a violet-blue. |
| `isGenerating?` | `boolean` |  | Controlled generating state. |
| `label?` | `string` | `"Generate"` | Idle label. |
| `leadingIcon?` | `React.ReactNode` |  | Icon before the label. Defaults to a sparkle. |
| `loading?` | `boolean` | `false` | Submitting state: spinner, aria-busy and a disabled button (separate from the generating glow). |
| `onGeneratingChange?` | `(generating: boolean) => void` |  | Called with the requested next state when the button is activated. |
| `size?` | `"xs" \| "sm" \| "md" \| "lg" \| "icon"` | `"md"` | Variant option from generateButtonVariants. |
| `trailingIcon?` | `React.ReactNode` |  | Icon after the label. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Native button with the Button focus ring. Generating is never triggered by focus alone.
- Only the visible label is in the accessibility tree, so the name is never doubled.
- A polite status region announces the generating label.

Keyboard:

| Key | Action |
| --- | --- |
| Enter | Requests the next state. |
| Space | Requests the next state. |

ARIA:

- `aria-busy` while generating or loading
- `role=status` live region with the generating label
- `data-generating` for styling hooks

- Reduced motion: Full motion sweeps a highlight across the label and pulses the sparkle. Subtle and none keep a static glow and the label swap only.

## Provenance

Adapted from Vengeance UI (MIT, Copyright (c) 2025-2026 Ashutoshx7). Upstream: https://github.com/Ashutoshx7/VengeanceUI/blob/0376d8e37b4a565016cce1064d7b96905c4494ab/src/components/ui/generate-button.tsx. Restyled to Glin tokens with accessibility and reduced motion review. Keep the attribution when you copy this component.

---

# Button Group

> Merges adjacent buttons into one segmented control with shared borders.

- id: `button-group`
- type: primitive
- category: Buttons
- tags: primitive
- docs: https://glinui.com/docs/components/radix/button-group
- markdown: https://glinui.com/md/button-group.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add button-group
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/button-group.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { ButtonGroupContext, ButtonGroup, ButtonGroupText, ButtonGroupSeparator, SURFACE_VARIANTS, SURFACE_TONES, SURFACE_ELEVATIONS, SURFACE_VARIANT_ALIASES } from "@glinui/ui"
```

## Usage

A range switcher and a split merge action sharing merged borders.

```tsx
"use client"

import { useState } from "react"
import { ArrowRight, Check } from "@phosphor-icons/react"
import { Button, ButtonGroup, ButtonGroupSeparator, Card, CardContent } from "@glinui/ui"

export function ButtonGroupToolbar() {
  const [range, setRange] = useState("week")
  return (
    <Card className="w-full max-w-xl">
      <CardContent className="flex flex-wrap items-center justify-between gap-3">
        <ButtonGroup aria-label="Time range">
          {["day", "week", "month"].map((value) => (
            <Button
              key={value}
              variant={range === value ? "solid" : "outline"}
              aria-pressed={range === value}
              onClick={() => setRange(value)}
            >
              {value === "day" ? "Day" : value === "week" ? "Week" : "Month"}
            </Button>
          ))}
        </ButtonGroup>
        <ButtonGroup aria-label="Pull request actions" variant="outline">
          <Button leadingIcon={<Check weight="bold" />}>Merge pull request</Button>
          <ButtonGroupSeparator />
          <Button size="icon" aria-label="More merge options">
            <ArrowRight weight="bold" className="rotate-90" />
          </Button>
        </ButtonGroup>
      </CardContent>
    </Card>
  )
}
```

### Variants

```tsx
import { Button, ButtonGroup } from "@glinui/ui"

export function Demo() {
  return (
    <div className="grid gap-3">
      <ButtonGroup variant="glinr" aria-label="Glinr"><Button>One</Button><Button>Two</Button></ButtonGroup>
      <ButtonGroup variant="solid" aria-label="Solid"><Button>One</Button><Button>Two</Button></ButtonGroup>
      <ButtonGroup variant="plain" aria-label="Plain"><Button>One</Button><Button>Two</Button></ButtonGroup>
      <ButtonGroup variant="outline" aria-label="Outline"><Button>One</Button><Button>Two</Button></ButtonGroup>
    </div>
  )
}
```

### Glass (opt-in)

```tsx
import { Button, ButtonGroup, ButtonGroupSeparator, ButtonGroupText } from "@glinui/ui"

// Glass needs a colorful or photographic backdrop to read.
export function Demo() {
  return (
    <ButtonGroup variant="glass" aria-label="Zoom">
      <Button>-</Button>
      <ButtonGroupText>100%</ButtonGroupText>
      <ButtonGroupSeparator />
      <Button>+</Button>
    </ButtonGroup>
  )
}
```

## Props

### ButtonGroupProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation?` | `"horizontal" \| "vertical"` | `"vertical"` | Variant option from buttonGroupVariants. |
| `size?` | `ButtonGroupContextValue["size"]` |  | Size applied to child Buttons that do not set their own. |
| `tone?` | `SurfaceTone` |  | Tone applied to child Buttons that do not set their own. |
| `variant?` | `"default" \| "glass" \| "glinr" \| "solid" \| "plain" \| "soft" \| "outline" \| "ghost" \| "gradient"` | `"default"` | Variant option from buttonGroupVariants. |

### ButtonGroupTextProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `asChild?` | `boolean` | `false` |  |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`, `glass`, `glinr`, `solid`, `plain`, `soft`, `outline`, `ghost`, `gradient`.

## Accessibility

- Renders `role="group"`; give it an `aria-label` describing the set.
- Each child keeps its own button semantics and focus ring (raised above neighbours).

Keyboard:

| Key | Action |
| --- | --- |
| Tab | Move through each button in order. |

ARIA:

- `role="group"` with `aria-label`
- `role="separator"` on ButtonGroupSeparator

- Reduced motion: Hover lift and press scale are disabled inside the group so merged edges stay aligned.

---

# Copy Button

> Raised pill that copies text, announces the result and resets after 1.6 seconds.

- id: `copy-button`
- type: primitive
- category: Buttons
- tags: primitive
- docs: https://glinui.com/docs/components/radix/copy-button
- markdown: https://glinui.com/md/copy-button.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add copy-button
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/copy-button.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { CopyButton } from "@glinui/ui"
```

## Usage

Labelled and icon-only copy buttons announce the result to screen readers.

```tsx
import { Card, CardContent, CardDescription, CardHeader, CardTitle, CopyButton } from "@glinui/ui"

export function CopyApiKey() {
  return (
    <Card className="w-full max-w-lg">
      <CardHeader>
        <CardTitle>API key</CardTitle>
        <CardDescription>Use this key to authenticate server requests. Treat it like a password.</CardDescription>
      </CardHeader>
      <CardContent className="space-y-3">
        <div className="flex items-center justify-between gap-3 rounded-lg border border-border/60 bg-[var(--surface-1)] px-3 py-2">
          <code className="truncate font-mono text-sm text-foreground">glin_live_4f9a7c21b6e8</code>
          <CopyButton value="glin_live_4f9a7c21b6e8" variant="outline" size="sm" label="Copy key" copiedLabel="Copied" />
        </div>
        <div className="flex items-center justify-between gap-3 rounded-lg border border-border/60 bg-[var(--surface-1)] px-3 py-2">
          <code className="truncate font-mono text-sm text-foreground">pnpm add @glinui/ui</code>
          <CopyButton value="pnpm add @glinui/ui" variant="ghost" size="icon" iconOnly label="Copy install command" />
        </div>
      </CardContent>
    </Card>
  )
}
```

### Icon only

```tsx
<CopyButton value="sk_live_123" iconOnly label="Copy key" />
```

### Variants

```tsx
<CopyButton value="x" variant="glinr" />
<CopyButton value="x" variant="solid" />
<CopyButton value="x" variant="plain" />
<CopyButton value="x" variant="soft" />
<CopyButton value="x" variant="outline" />
<CopyButton value="x" variant="ghost" />
```

## Props

### CopyButtonProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `copiedLabel?` | `string` | `"Copied"` | Label shown (and announced) after copying. |
| `getValue?` | `() => string` |  | Lazily resolve the text to copy (wins over `value`). |
| `iconOnly?` | `boolean` | `false` | Hide the text label and keep only the icon (label stays as the accessible name). |
| `label?` | `string` | `"Copy"` | Idle label. |
| `onCopy?` | `(value: string) => void` |  | Called after a successful copy with the copied text (analytics hook). |
| `resetMs?` | `number` | `1600` | Milliseconds before returning to the idle state. |
| `value?` | `string` | `""` | Static text to copy. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Native button; the result is announced through a polite live region.
- data-copied reflects state for styling hooks.
- Falls back to document.execCommand when the Clipboard API is unavailable.

Keyboard:

| Key | Action |
| --- | --- |
| Enter / Space | Copies the text. |

ARIA:

- role=status live region with the copied label
- aria-label when iconOnly

- Reduced motion: Only a 1px press translate, removed under reduced motion.

---

# Toggle

> A two-state button that can be pressed on or off.

- id: `toggle`
- type: primitive
- category: Buttons
- tags: primitive
- docs: https://glinui.com/docs/components/radix/toggle
- markdown: https://glinui.com/md/toggle.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add toggle
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/toggle.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Toggle, CONTROL_LEGACY_VARIANTS, CONTROL_SIZE_CLASSES, GlinProvider, GLIN_MOTIONS, GLIN_ENGINES, GLIN_SURFACES, GLIN_STYLES } from "@glinui/ui"
```

## Usage

Toggles and toggle groups in an editor toolbar.

```tsx
import { BellRinging, TextAlignCenter, TextAlignLeft, TextAlignRight, TextB, TextItalic, TextUnderline } from "@phosphor-icons/react"
import { Card, CardContent, Toggle, ToggleGroup, ToggleGroupItem } from "@glinui/ui"

export function ToggleEditorToolbar() {
  return (
    <Card className="w-full max-w-lg">
      <CardContent className="space-y-4">
        <div role="toolbar" aria-label="Text formatting" className="flex flex-wrap items-center gap-2">
          <ToggleGroup type="multiple" defaultValue={["bold", "italic"]} aria-label="Text style">
            <ToggleGroupItem value="bold" aria-label="Bold"><TextB weight="bold" /></ToggleGroupItem>
            <ToggleGroupItem value="italic" aria-label="Italic"><TextItalic weight="bold" /></ToggleGroupItem>
            <ToggleGroupItem value="underline" aria-label="Underline"><TextUnderline weight="bold" /></ToggleGroupItem>
          </ToggleGroup>
          <ToggleGroup type="single" defaultValue="left" aria-label="Alignment">
            <ToggleGroupItem value="left" aria-label="Align left"><TextAlignLeft /></ToggleGroupItem>
            <ToggleGroupItem value="center" aria-label="Align center"><TextAlignCenter /></ToggleGroupItem>
            <ToggleGroupItem value="right" aria-label="Align right"><TextAlignRight /></ToggleGroupItem>
          </ToggleGroup>
          <Toggle aria-label="Notify subscribers" defaultPressed variant="soft">
            <BellRinging weight="bold" />
          </Toggle>
        </div>
        <p className="rounded-lg border border-border/60 bg-[var(--surface-1)] p-3 text-sm text-foreground">
          Weekly digest: three launches, one deprecation and a new way to schedule deploys.
        </p>
      </CardContent>
    </Card>
  )
}
```

### Variants

Each variant in the pressed state.

```tsx
import { Toggle } from "@glinui/ui"
import { TextB } from "@phosphor-icons/react"

export function Demo() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <Toggle variant="glinr" defaultPressed aria-label="glinr"><TextB /></Toggle>
      <Toggle variant="solid" defaultPressed aria-label="solid"><TextB /></Toggle>
      <Toggle variant="plain" defaultPressed aria-label="plain"><TextB /></Toggle>
      <Toggle variant="soft" defaultPressed aria-label="soft"><TextB /></Toggle>
      <Toggle variant="outline" defaultPressed aria-label="outline"><TextB /></Toggle>
      <Toggle variant="ghost" defaultPressed aria-label="ghost"><TextB /></Toggle>
    </div>
  )
}
```

### Glass (opt-in)

Glass is opt-in and needs a backdrop behind it: pick Photo or Vivid in the stage backdrop switcher.

```tsx
import { Toggle } from "@glinui/ui"
import { TextUnderline } from "@phosphor-icons/react"

export function Demo() {
  return (
    <Toggle variant="glass" size="lg" defaultPressed aria-label="Underline">
      <TextUnderline />
    </Toggle>
  )
}
```

## Props

### ToggleProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from toggleVariants. |
| `variant?` | `ControlVariantProp` |  | Surface look. Omit to follow the ambient design style (glinr = raised key that presses in when on). Also: solid, plain, soft, outline, gh... |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Renders a native button with `aria-pressed`.
- Icon-only toggles need an `aria-label`.
- Visible violet focus ring on `:focus-visible`.

Keyboard:

| Key | Action |
| --- | --- |
| Enter / Space | Toggle the pressed state. |
| Tab | Move focus to the toggle. |

ARIA:

- `aria-pressed` reflects state
- `data-state="on|off"` for styling

- Reduced motion: Colour transitions are removed under prefers-reduced-motion.

---

# Toggle Group

> A set of toggles with single or multiple selection and merged segmented borders.

- id: `toggle-group`
- type: primitive
- category: Buttons
- tags: primitive
- docs: https://glinui.com/docs/components/radix/toggle-group
- markdown: https://glinui.com/md/toggle-group.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add toggle-group
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/toggle-group.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { ToggleGroup, ToggleGroupItem, CONTROL_LEGACY_VARIANTS, CONTROL_SIZE_CLASSES, GlinProvider, GLIN_MOTIONS, GLIN_ENGINES, GLIN_SURFACES } from "@glinui/ui"
```

## Usage

A single-select group that switches the layout of a list.

```tsx
"use client"

import { useState } from "react"
import { Card, CardContent, CardHeader, CardTitle, ToggleGroup, ToggleGroupItem } from "@glinui/ui"

export function ToggleViewSwitcher() {
  const [view, setView] = useState("list")
  const rows = ["Atlas redesign", "Billing migration", "Mobile onboarding"]
  return (
    <Card className="w-full max-w-lg">
      <CardHeader>
        <div className="flex items-center justify-between gap-3">
          <CardTitle>Projects</CardTitle>
          <ToggleGroup
            type="single"
            value={view}
            onValueChange={(next) => next && setView(next)}
            aria-label="Layout"
            size="sm"
          >
            <ToggleGroupItem value="list">List</ToggleGroupItem>
            <ToggleGroupItem value="grid">Grid</ToggleGroupItem>
          </ToggleGroup>
        </div>
      </CardHeader>
      <CardContent>
        <ul className={view === "grid" ? "grid grid-cols-3 gap-2" : "grid gap-2"}>
          {rows.map((row) => (
            <li key={row} className="rounded-lg border border-border/60 bg-[var(--surface-1)] px-3 py-2 text-sm text-foreground">
              {row}
            </li>
          ))}
        </ul>
      </CardContent>
    </Card>
  )
}
```

### Variants

```tsx
import { ToggleGroup, ToggleGroupItem } from "@glinui/ui"

export function Demo() {
  return (
    <div className="flex flex-col items-start gap-3">
      <ToggleGroup type="single" variant="glinr" defaultValue="week" aria-label="glinr">
        <ToggleGroupItem value="day">Day</ToggleGroupItem>
        <ToggleGroupItem value="week">Week</ToggleGroupItem>
        <ToggleGroupItem value="month">Month</ToggleGroupItem>
      </ToggleGroup>
      <ToggleGroup type="single" variant="solid" defaultValue="week" aria-label="solid">
        <ToggleGroupItem value="day">Day</ToggleGroupItem>
        <ToggleGroupItem value="week">Week</ToggleGroupItem>
        <ToggleGroupItem value="month">Month</ToggleGroupItem>
      </ToggleGroup>
      <ToggleGroup type="single" variant="plain" defaultValue="week" aria-label="plain">
        <ToggleGroupItem value="day">Day</ToggleGroupItem>
        <ToggleGroupItem value="week">Week</ToggleGroupItem>
        <ToggleGroupItem value="month">Month</ToggleGroupItem>
      </ToggleGroup>
      <ToggleGroup type="single" variant="soft" defaultValue="week" aria-label="soft">
        <ToggleGroupItem value="day">Day</ToggleGroupItem>
        <ToggleGroupItem value="week">Week</ToggleGroupItem>
        <ToggleGroupItem value="month">Month</ToggleGroupItem>
      </ToggleGroup>
      <ToggleGroup type="single" variant="outline" defaultValue="week" aria-label="outline">
        <ToggleGroupItem value="day">Day</ToggleGroupItem>
        <ToggleGroupItem value="week">Week</ToggleGroupItem>
        <ToggleGroupItem value="month">Month</ToggleGroupItem>
      </ToggleGroup>
      <ToggleGroup type="single" variant="ghost" defaultValue="week" aria-label="ghost">
        <ToggleGroupItem value="day">Day</ToggleGroupItem>
        <ToggleGroupItem value="week">Week</ToggleGroupItem>
        <ToggleGroupItem value="month">Month</ToggleGroupItem>
      </ToggleGroup>
    </div>
  )
}
```

### Multiple with spacing

```tsx
import { ToggleGroup, ToggleGroupItem } from "@glinui/ui"
import { TextB, TextItalic } from "@phosphor-icons/react"

export function Demo() {
  return (
    <ToggleGroup type="multiple" variant="outline" spacing={2} aria-label="Format">
      <ToggleGroupItem value="bold" aria-label="Bold"><TextB /></ToggleGroupItem>
      <ToggleGroupItem value="italic" aria-label="Italic"><TextItalic /></ToggleGroupItem>
    </ToggleGroup>
  )
}
```

## Props

### ToggleGroupItemProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant?` | `ControlVariantProp` |  |  |

### ToggleGroupProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `spacing?` | `ToggleGroupSpacing` | `0` | Gap between items. 0 merges items into one segmented control. |
| `variant?` | `ControlVariantProp` |  | Surface look for every item. Omit to follow the ambient design style. Same vocabulary as Toggle. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Single mode exposes `radiogroup` with `radio` items, multiple mode exposes `group` with toggle buttons.
- Roving tabindex: one tab stop for the whole group.
- Always label the group with `aria-label`.

Keyboard:

| Key | Action |
| --- | --- |
| Arrow keys | Move focus between items. |
| Enter / Space | Toggle the focused item. |
| Home / End | Move to first or last item. |

ARIA:

- `aria-label` on group
- `aria-checked` (single) or `aria-pressed` (multiple) on items

- Reduced motion: Item colour transitions are disabled under prefers-reduced-motion.

---

# Glass Toggle

> Toggle switch with liquid fill animation and frosted glass surface.

- id: `glass-toggle`
- type: signature
- category: Buttons
- tags: signature
- docs: https://glinui.com/docs/components/glass-toggle
- markdown: https://glinui.com/md/glass-toggle.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add glass-toggle
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/glass-toggle.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { GlassToggle } from "@glinui/ui"
```

## Usage

```tsx
"use client"
import { GlassToggle } from "@glinui/ui"

export function GlassOnPhoto() {
  return (
    <div className="bg-[url('/photo.jpg')] p-8">
      <GlassToggle defaultChecked />
    </div>
  )
}
```

```tsx
"use client"
import { GlassToggle } from "@glinui/ui"

export function GlassToggleColorDemo() {
  return (
    <div className="flex items-center justify-center gap-6 p-8">
      <GlassToggle defaultChecked activeColor="#22c55e" />
      <GlassToggle defaultChecked activeColor="#6366f1" />
      <GlassToggle defaultChecked activeColor="#f43f5e" />
    </div>
  )
}
```

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Renders with `role="switch"` and `aria-checked`.
- Supports keyboard activation (Space) and a visible focus ring.
- Native form participation through `name`, `value`, `required` and `form`.
- `loading` sets `aria-busy` and makes the toggle inert.
- 44px minimum hit area at every size; thumb moves toward the inline end in RTL.
- Disabled state reduces opacity and blocks interaction.
- Reduced motion: When `prefers-reduced-motion: reduce` is active, or `data-glin-motion` is `none` or `subtle`, the thumb and fill change state instantly with no sliding transform.

---

# Text

> Body text primitive for default, muted, and glass-highlighted copy.

- id: `text`
- type: primitive
- category: Text and code
- tags: primitive
- docs: https://glinui.com/docs/components/radix/text
- markdown: https://glinui.com/md/text.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add text
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/text.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Text } from "@glinui/ui"
```

## Usage

Eyebrow, lead, body and caption sizes build a clear reading order.

```tsx
import { Code, Heading, Text } from "@glinui/ui"

export function ReleaseNote() {
  return (
    <article className="flex w-full max-w-2xl flex-col gap-5 text-left">
      <Text variant="eyebrow">Release notes</Text>
      <Heading level={2} size="h2">Version 4.2 is out</Heading>
      <Text size="lg">Scheduled exports now run in your timezone, and the audit log keeps 400 days of history on every plan.</Text>
      <Text variant="muted">Existing schedules migrate automatically. If you pinned a UTC offset in the API, it keeps working, and the new <Code>timezone</Code> field takes priority when both are set.</Text>
      <Text size="sm" variant="muted">Published Oct 7, 2026. Questions? Reply to this post or write to support.</Text>
    </article>
  )
}
```

### Variants

Default, muted, eyebrow, ghost and glass on a vivid backdrop.

```tsx
import { Text } from "@glinui/ui"

export function TextVariants() {
  return (
    <div data-glin-theme="dark" className="flex w-full flex-wrap items-center justify-center gap-4 rounded-xl bg-gradient-to-br from-indigo-600 via-purple-600 to-pink-500 p-8">
      <Text>Default</Text>
      <Text variant="muted" className="text-[var(--color-foreground)]">Muted</Text>
      <Text variant="eyebrow" className="text-[var(--color-foreground)]">Eyebrow</Text>
      <Text variant="ghost">Ghost</Text>
      <Text variant="glass">Glass</Text>
    </div>
  )
}
```

### In a layout

Short entries in a changelog, paired with Badge.

```tsx
import { Badge, Heading, Text } from "@glinui/ui"

const entries = [
  { date: "Oct 7", tag: "New", tone: "accent", text: "Scheduled exports follow the workspace timezone." },
  { date: "Sep 29", tag: "Fixed", tone: "success", text: "Invoice PDFs no longer clip long company names." },
  { date: "Sep 18", tag: "Changed", tone: "warning", text: "API keys created before 2024 now expire after 12 months." }
] as const

export function Changelog() {
  return (
    <section aria-label="Changelog" className="flex w-full max-w-xl flex-col gap-4 rounded-2xl border border-[var(--line-soft)] bg-[var(--surface-1)] p-6 text-left">
      <Heading level={2} size="sm">Changelog</Heading>
      <ol className="flex flex-col gap-4">
        {entries.map((entry) => (
          <li key={entry.date} className="grid grid-cols-[4.5rem_1fr] items-start gap-3">
            <Text size="sm" variant="muted">{entry.date}</Text>
            <div className="flex flex-col items-start gap-1.5">
              <Badge tone={entry.tone} variant="soft">{entry.tag}</Badge>
              <Text>{entry.text}</Text>
            </div>
          </li>
        ))}
      </ol>
    </section>
  )
}
```

## Props

### TextProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as?` | `"p" \| "span" \| "div"` | `"p"` | Element to render. Use `span` with `tone` for an inline mark. |
| `dot?` | `boolean` | `false` | Eyebrow variant only: show the accent dot before the label. |
| `lead?` | `"true" \| "false"` | `false` | Variant option from textVariants. |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from textVariants. |
| `tone?` | `"live" \| "violet"` |  | Variant option from textVariants. |
| `variant?` | `"default" \| "muted" \| "glass" \| "ghost" \| "eyebrow"` | `"default"` | Variant option from textVariants. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`, `muted`, `glass`, `ghost`, `eyebrow`.

## Accessibility

- Renders semantic paragraph text by default.
- `Text` renders a `<p>` element, which carries implicit paragraph semantics for screen readers.
- Avoid nesting block-level elements inside `<Text>`, use inline elements such as `<strong>` or `<em>` for emphasis within copy.
- Color-only meaning (e.g. muted = disabled) must be supplemented with `aria-disabled` or equivalent on the containing control.
- Reduced motion: No motion-dependent behavior. `Text` is a static element with no animation. It is unaffected by `prefers-reduced-motion`.

---

# Heading

> Semantic heading primitive with independent style scaling.

- id: `heading`
- type: primitive
- category: Text and code
- tags: primitive
- docs: https://glinui.com/docs/components/radix/heading
- markdown: https://glinui.com/md/heading.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add heading
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/heading.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Heading } from "@glinui/ui"
```

## Usage

Display heading with an eyebrow, lead, and byline. The size prop sets the scale, level sets the outline.

```tsx
import { Avatar, Heading, Text } from "@glinui/ui"

export function ArticleHeader() {
  return (
    <article className="flex w-full max-w-2xl flex-col gap-5 text-left">
      <Text variant="eyebrow">Engineering, 8 min read</Text>
      <Heading level={1} size="display">How we cut cold starts from 900 ms to 90 ms</Heading>
      <Text size="lg" variant="muted">A walk through snapshotting, lazy imports and the one runtime flag that did most of the work.</Text>
      <div className="flex items-center gap-3">
        <Avatar fallback="MK" size="md" />
        <div className="flex flex-col">
          <span className="text-sm font-medium text-[var(--color-foreground)]">Maya Kovacs</span>
          <span className="text-xs text-[var(--color-muted)]">Platform team, Oct 7 2026</span>
        </div>
      </div>
    </article>
  )
}
```

### Type scale

Six sizes, independent of the semantic level.

```tsx
import { Heading } from "@glinui/ui"

const scale = ["display", "h2", "h3", "lg", "md", "sm"] as const

export function TypeScale() {
  return (
    <div className="flex w-full max-w-2xl flex-col divide-y divide-[var(--line-soft)] rounded-xl border border-[var(--line-soft)] bg-[var(--surface-1)] text-left">
      {scale.map((size) => (
        <div key={size} className="flex items-baseline justify-between gap-4 px-5 py-3">
          <Heading level={2} size={size}>Quarterly review</Heading>
          <code className="shrink-0 font-mono text-xs text-[var(--color-muted)]">size="{size}"</code>
        </div>
      ))}
    </div>
  )
}
```

### Variants

Outline, ghost and glass surfaces. Glass needs a colorful backdrop behind it.

```tsx
import { Heading } from "@glinui/ui"

export function HeadingVariants() {
  return (
    <div data-glin-theme="dark" className="flex w-full flex-wrap items-center justify-center gap-4 rounded-xl bg-gradient-to-br from-indigo-600 via-purple-600 to-pink-500 p-8">
      <Heading level={3} size="sm">Default</Heading>
      <Heading level={3} size="sm" variant="outline">Outline</Heading>
      <Heading level={3} size="sm" variant="ghost">Ghost</Heading>
      <Heading level={3} size="sm" variant="glass">Glass</Heading>
    </div>
  )
}
```

## Props

### HeadingProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `level?` | `HeadingLevel` | `2` |  |
| `size?` | `"sm" \| "md" \| "lg" \| "display" \| "h2" \| "h3"` | `"md"` | Variant option from headingVariants. |
| `variant?` | `"default" \| "glass" \| "outline" \| "ghost"` | `"default"` | Variant option from headingVariants. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`, `glass`, `outline`, `ghost`.

## Accessibility

- Preserves semantic heading hierarchy with configurable level.
- Always use headings in a logical, non-skipping order (h1 → h2 → h3) to maintain a coherent document outline for screen readers.
- The `level` prop controls the rendered HTML tag, never override this with CSS `display` tricks that break semantics.
- Decoupling `level` from `size` lets you meet visual design requirements without compromising heading hierarchy.
- Avoid using multiple `level={1}` headings on a single page; pages should have exactly one `<h1>`.
- Reduced motion: No motion-dependent behavior. `Heading` is a static text primitive with no animation. No reduced-motion considerations apply.

---

# Text Reveal

> Word-by-word opacity reveal driven by scroll position.

- id: `text-reveal`
- type: signature
- category: Text and code
- tags: signature
- docs: https://glinui.com/docs/components/text-reveal
- markdown: https://glinui.com/md/text-reveal.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add text-reveal
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/text-reveal.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { TextReveal, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider } from "@glinui/ui"
```

## Usage

```tsx
import { TextReveal } from "@glinui/ui"

export function TextRevealLongDemo() {
  return (
    <TextReveal text="Design systems should feel alive. Every surface, every transition, every interaction should respond with purpose. Glin UI makes this effortless with composable glass primitives built for modern React." />
  )
}
```

## Props

### TextRevealProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `duration?` | `number` |  | Duration per word in ms (`reveal` mode). |
| `engine?` | `EngineName` |  | Engine override: `css` (default), `motion`, `gsap` or a registered custom engine. |
| `immediate?` | `boolean` | `false` | Play on mount instead of waiting for the viewport (`reveal` mode). |
| `mode?` | `"scroll" \| "reveal"` | `"scroll"` | `scroll` (default) scrubs word opacity with scroll position and is css only. `reveal` plays a timed word-by-word reveal once in view, dri... |
| `motion?` | `MotionLevel` |  | Motion override. `none` renders the static final state, `subtle` is opacity only. |
| `step?` | `number` | `60` | Delay between words in ms (`reveal` mode). Default 60. |
| `text` | `string` |  |  |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- All text is in the DOM and readable by screen readers at all times.
- Opacity is visual only, content is never hidden from assistive technologies.
- Reduced motion: When `prefers-reduced-motion` is active, all words are immediately shown at full opacity.

---

# Reveal Text

> Text that reveals through a clip-path wipe animation triggered on view.

- id: `reveal-text`
- type: signature
- category: Text and code
- tags: signature
- docs: https://glinui.com/docs/components/reveal-text
- markdown: https://glinui.com/md/reveal-text.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add reveal-text
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/reveal-text.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { RevealText, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider } from "@glinui/ui"
```

## Usage

```tsx
"use client"
import { RevealText } from "@glinui/ui"

export function RevealTextDirectionsDemo() {
  return (
    <div className="flex flex-col items-center gap-4 p-8">
      <h3 className="text-2xl font-bold"><RevealText text="From Left" direction="left" /></h3>
      <h3 className="text-2xl font-bold"><RevealText text="From Right" direction="right" delay={200} /></h3>
      <h3 className="text-2xl font-bold"><RevealText text="From Top" direction="top" delay={400} /></h3>
      <h3 className="text-2xl font-bold"><RevealText text="From Bottom" direction="bottom" delay={600} /></h3>
    </div>
  )
}
```

## Props

### RevealTextProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `delay?` | `number` | `0` | Delay before animation starts, in ms |
| `direction?` | `"left" \| "right" \| "top" \| "bottom"` | `"left"` | Reveal direction |
| `duration?` | `number` | `0.8` | Animation duration in seconds |
| `engine?` | `EngineName` |  | Engine override: `css` (default), `motion`, `gsap` or a registered custom engine. |
| `motion?` | `MotionLevel` |  | Motion override. `none` renders the static final state, `subtle` is opacity only. |
| `text` | `string` |  | Text to reveal |
| `threshold?` | `number` | `0.5` | Intersection threshold |
| `triggerOnView?` | `boolean` | `true` | Trigger on intersection |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- The text content is always present in the DOM for screen readers.
- The animation is purely visual via `clip-path`.
- Reduced motion: When `prefers-reduced-motion: reduce` is active, the text is shown immediately with no animation.

---

# Typewriter

> Character-by-character typing animation with blinking cursor and loop support.

- id: `typewriter`
- type: signature
- category: Text and code
- tags: signature
- docs: https://glinui.com/docs/components/typewriter
- markdown: https://glinui.com/md/typewriter.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add typewriter
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/typewriter.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Typewriter, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider } from "@glinui/ui"
```

## Usage

```tsx
"use client"
import { Typewriter } from "@glinui/ui"

export function TypewriterWordsDemo() {
  return (
    <div className="flex items-center justify-center p-8">
      <h2 className="text-3xl font-bold">
        Build{" "}
        <Typewriter
          words={["interfaces", "experiences", "products", "the future"]}
          speed={60}
          deleteSpeed={40}
          pauseDuration={2000}
          className="text-accent"
        />
      </h2>
    </div>
  )
}
```

```tsx
"use client"
import { Typewriter } from "@glinui/ui"

export function TypewriterLoopDemo() {
  return (
    <div className="flex items-center justify-center p-8">
      <p className="text-xl font-medium text-[var(--color-muted)]">
        <Typewriter
          text="Building the future of UI..."
          loop
          speed={60}
          pauseDuration={2000}
        />
      </p>
    </div>
  )
}
```

```tsx
"use client"
import { Typewriter } from "@glinui/ui"

export function TypewriterCustomDemo() {
  return (
    <div className="flex items-center justify-center p-8">
      <code className="text-lg font-mono text-accent">
        <Typewriter
          text="npm install @glinui/ui"
          speed={30}
          cursorChar="_"
          delay={500}
        />
      </code>
    </div>
  )
}
```

## Props

### TypewriterProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `cursor?` | `boolean` | `true` | Show a blinking cursor. Default: true |
| `cursorChar?` | `string` | `"\|"` | The cursor character. Default: "\|" |
| `delay?` | `number` | `0` | Initial delay before typing starts, in ms. Default: 0 |
| `deleteSpeed?` | `number` | `30` | Milliseconds per character when deleting. Default: 30 |
| `engine?` | `EngineName` |  | Engine override: `css` (default), `motion`, `gsap` or a registered custom engine. |
| `loop?` | `boolean` | `false` | Loop the typing animation. Default: false |
| `motion?` | `MotionLevel` |  | Motion override. `none` renders the static final state, `subtle` is opacity only. |
| `onComplete?` | `() => void` |  | Callback fired when a word finishes typing (fires per cycle). |
| `pauseDuration?` | `number` | `1500` | Pause at end before deleting/retyping, in ms. Default: 1500 |
| `speed?` | `number` | `50` | Milliseconds per character when typing. Default: 50 |
| `text?` | `string` |  | The text to type out (single string mode). |
| `words?` | `string[]` |  | Array of words/phrases to cycle through (multi-word mode). |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- The component renders with `aria-label` set to the full `text` value so screen readers announce the complete text immediately.
- The typed characters and cursor are both `aria-hidden="true"` to prevent partial reading.
- No interactive elements are created by the typewriter itself.
- Reduced motion: When `prefers-reduced-motion: reduce` is active, the full text is displayed immediately with no animation. The cursor remains visible but does not blink.

---

# Word Rotate

> Cycling text animation that rotates through an array of words.

- id: `word-rotate`
- type: signature
- category: Text and code
- tags: signature
- docs: https://glinui.com/docs/components/word-rotate
- markdown: https://glinui.com/md/word-rotate.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add word-rotate
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/word-rotate.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { WordRotate, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider } from "@glinui/ui"
```

## Usage

```tsx
"use client"
import { WordRotate } from "@glinui/ui"

export function WordRotateFastDemo() {
  return (
    <div className="flex items-center justify-center p-8">
      <h2 className="text-3xl font-bold">
        Powered by{" "}
        <WordRotate
          words={["speed", "precision", "glass", "motion"]}
          duration={1500}
          className="text-accent"
        />
      </h2>
    </div>
  )
}
```

## Props

### WordRotateProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `animationDuration?` | `number` | `300` | Animation speed for enter/exit (ms) |
| `duration?` | `number` | `2500` | Duration each word is shown (ms) |
| `engine?` | `EngineName` |  | Engine override: `css` (default), `motion`, `gsap` or a registered custom engine. |
| `motion?` | `MotionLevel` |  | Motion override. `none` renders the static final state, `subtle` is opacity only. |
| `words` | `string[]` |  | Array of words to cycle through |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- The component renders with `aria-live="polite"` so screen readers announce each new word as it appears.
- The outgoing word is removed from the DOM after its exit animation, preventing duplicate announcements.
- Surrounding static text is not affected by the live region and is read normally.
- Reduced motion: When `prefers-reduced-motion: reduce` is active, word cycling stops and the first word in the `words` array is displayed statically without any animation.

---

# Chromatic Text

> Text with chromatic aberration effect, RGB channel splitting.

- id: `chromatic-text`
- type: signature
- category: Text and code
- tags: signature
- docs: https://glinui.com/docs/components/chromatic-text
- markdown: https://glinui.com/md/chromatic-text.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add chromatic-text
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/chromatic-text.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { ChromaticText } from "@glinui/ui"
```

## Usage

```tsx
import { Badge, Button, ChromaticText, Text } from "@glinui/ui"

export function EventTeaser() {
  return (
    <section data-glin-theme="dark" className="relative isolate flex min-h-[22rem] w-full flex-col items-center justify-center gap-5 overflow-hidden rounded-xl bg-[var(--surface-0)] px-6 py-14 text-center">
      <Badge tone="accent" variant="soft">Live, Nov 12</Badge>
      <h1 className="max-w-3xl text-4xl font-semibold tracking-tight text-[var(--color-foreground)] sm:text-6xl">
        <ChromaticText>Signal</ChromaticText> Conf 2026
      </h1>
      <Text size="lg" variant="muted" className="max-w-xl">One day of talks on realtime systems, observability and the humans who carry the pager.</Text>
      <div className="flex flex-wrap justify-center gap-3">
        <Button size="lg">Get a ticket</Button>
        <Button size="lg" variant="outline">View speakers</Button>
      </div>
    </section>
  )
}
```

```tsx
import { ChromaticText } from "@glinui/ui"

export function ChromaticVariants() {
  return (
    <div data-glin-theme="dark" className="flex w-full flex-wrap items-center justify-center gap-x-10 gap-y-4 rounded-xl bg-[var(--surface-0)] p-8">
      <ChromaticText className="text-4xl font-semibold text-[var(--color-foreground)]">Default</ChromaticText>
      <ChromaticText duration={3} offset={3} className="text-4xl font-semibold text-[var(--color-foreground)]">Glitch</ChromaticText>
      <ChromaticText colors={["#06b6d4", "#f97316"]} offset={4} className="text-4xl font-semibold text-[var(--color-foreground)]">Neon</ChromaticText>
    </div>
  )
}
```

## Props

### ChromaticTextProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `colors?` | `[string, string]` | `["var(--tone-danger)", "var(--tone-in...` | Colors for the channels [red, blue]. Defaults come from theme tokens; the fringes sit behind the base text so they read on any stage. |
| `duration?` | `number` | `0` | Animation duration in seconds (0 = static) |
| `offset?` | `number` | `2` | Offset amount in px for the chromatic split |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Ghost layers are `aria-hidden="true"`, screen readers only see the base text.
- The base text remains fully readable and accessible.
- Reduced motion: When `prefers-reduced-motion: reduce` is active, the animated chromatic shift is paused via `motion-reduce:[animation:none]`. The static offset layers remain visible.

---

# Hyper Text

> Text that scrambles through random characters and settles on the real string, on hover, in view or on mount.

- id: `hyper-text`
- type: primitive
- category: Text and code
- tags: primitive, adapted
- docs: https://glinui.com/docs/components/radix/hyper-text
- markdown: https://glinui.com/md/hyper-text.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add hyper-text
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/hyper-text.json
```

Package:

```bash
npm install @glinui/ui @glinui/motion @glinui/tokens
```

## Import

```tsx
import { HyperText, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider } from "@glinui/ui"
```

## Usage

Adapted from Hyper Text by Magic UI (MIT).

Improvements: no motion dependency (a single rAF loop), per code point cells with no layout shift, graphemes kept together for emoji and combining marks, view and mount triggers, SSR renders the final text so there is no hydration mismatch, and every frame and timer is cancelled on unmount.

Engines: this component drives its main animation through the pluggable motion engine. Pass `engine` (css, motion or gsap), wrap a subtree in `MotionEngineProvider`, or set `data-glin-engine` on `<html>`. The css engine is built in and dependency free; motion and gsap are opt-in via `@glinui/motion/register/*`. `motion="none"` renders the final state and `subtle` is opacity only.

Hover or focus the heading to re-run the scramble.

```tsx
import { Badge, HyperText } from "@glinui/ui"

export function Demo() {
  return (
    <div className="flex flex-col items-start gap-3 p-6">
      <Badge>Changelog</Badge>
      <HyperText trigger="mount" duration={1000}>Version 0.4 is live</HyperText>
      <p className="text-sm text-[var(--color-muted)]">Hover the headline to scramble it again.</p>
    </div>
  )
}
```

### On view with custom characters

Runs once when scrolled into view, scrambling through binary digits.

```tsx
import { HyperText } from "@glinui/ui"

export function Demo() {
  return (
    <HyperText trigger="view" characterSet="01" duration={1200} as="h3">
      Decrypting signal
    </HyperText>
  )
}
```

### Proportional glyphs

Turn off tabular cells to use the natural font width.

```tsx
import { HyperText } from "@glinui/ui"

export function Demo() {
  return <HyperText tabular={false} className="font-sans text-2xl">Mixed width</HyperText>
}
```

## Props

### HyperTextProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as?` | `HyperTextTag` | `"div"` | Element to render. |
| `characterSet?` | `string \| readonly string[]` | `DEFAULT_CHARACTER_SET` | Characters used while scrambling. Defaults to A to Z. |
| `children` | `string` |  | The text to reveal. |
| `delay?` | `number` | `0` | Delay before an automatic run (view or mount) in milliseconds. |
| `duration?` | `number` | `800` | Scramble length in milliseconds. |
| `engine?` | `EngineName` |  | Engine override: `css` (default), `motion`, `gsap` or a registered custom engine. |
| `focusable?` | `boolean` | `false` | Make the element tabbable so keyboard users can trigger the hover effect. |
| `motion?` | `MotionLevel` |  | Motion override. `none` renders the static final state, `subtle` is opacity only. |
| `tabular?` | `boolean` | `true` | Render every glyph in a one character wide cell so the line never changes width. |
| `trigger?` | `HyperTextTrigger` | `"hover"` | When the scramble runs: pointer or keyboard focus, once in view, or once on mount. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- The real string is always present in a screen reader only span; the scrambling glyph layer is aria-hidden.
- Assistive tech never reads random characters.
- With focusable, keyboard focus triggers the same effect as hover and shows a visible focus ring.

Keyboard:

| Key | Action |
| --- | --- |
| Tab | Focus the text (only when focusable is set) to run the scramble. |

ARIA:

- `aria-hidden` on the glyph layer
- real text in an `sr-only` span

- Reduced motion: With prefers-reduced-motion, or Glin motion level none or subtle, no scramble runs and the final text is shown immediately.

## Provenance

Adapted from Magic UI (MIT, Copyright (c) Magic UI). Upstream: https://magicui.design/docs/components/hyper-text. Restyled to Glin tokens with accessibility and reduced motion review. Keep the attribution when you copy this component.

---

# Morphing Text

> Cycles through words with a gooey blur and threshold morph, paused off screen and static under reduced motion.

- id: `morphing-text`
- type: primitive
- category: Text and code
- tags: primitive, adapted
- docs: https://glinui.com/docs/components/radix/morphing-text
- markdown: https://glinui.com/md/morphing-text.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add morphing-text
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/morphing-text.json
```

Package:

```bash
npm install @glinui/ui @glinui/motion @glinui/tokens
```

## Import

```tsx
import { MorphingText, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider } from "@glinui/ui"
```

## Usage

Adapted from Morphing Text by Magic UI (MIT).

Improvements: the SVG filter id is unique per instance (the original used a global id that collides), the loop pauses off screen, large frame gaps are clamped, text size is container relative with clamp, and initial markup is the first text, readable before JS runs.

Difference from Word Rotate: Morphing Text is a blur and threshold gooey crossfade in place, Word Rotate swaps words with a vertical slide.

Engines: the `engine` prop is not applicable. Continuous glyph cross-fade driven by a css filter loop; an engine adds nothing.

Cycles through three words.

```tsx
import { MorphingText } from "@glinui/ui"

export function Demo() {
  return (
    <div className="flex flex-col items-center gap-2 p-6">
      <p className="text-sm text-[var(--color-muted)]">Your workspace is</p>
      <MorphingText texts={["Faster", "Calmer", "Yours"]} className="h-16 w-full max-w-md text-5xl font-bold" />
    </div>
  )
}
```

### Slower timing

Longer morph and rest times, smaller text via className.

```tsx
import { MorphingText } from "@glinui/ui"

export function Demo() {
  return (
    <MorphingText
      texts={["Calm", "Clear", "Considered"]}
      morphTime={2.4}
      cooldownTime={1.2}
      className="text-[var(--color-accent)]"
    />
  )
}
```

## Props

### MorphingTextProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `cooldownTime?` | `number` | `0.5` | Seconds each text rests before the next morph. |
| `morphTime?` | `number` | `1.5` | Seconds a morph takes. |
| `texts` | `string[]` |  | Words or phrases to cycle through. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- All texts are exposed once in a screen reader only span, so the animation never spams a live region.
- The visual layer is aria-hidden.
- The loop pauses while the component is off screen and in background tabs.

ARIA:

- `aria-hidden` on the visual layer
- all texts joined in an `sr-only` span

- Reduced motion: Motion level none (or prefers-reduced-motion) shows the first text and runs no loop. Level subtle swaps texts with a plain opacity crossfade, no blur and no filter.

## Provenance

Adapted from Magic UI (MIT, Copyright (c) Magic UI). Upstream: https://magicui.design/docs/components/morphing-text. Restyled to Glin tokens with accessibility and reduced motion review. Keep the attribution when you copy this component.

---

# Sparkles Text

> Text with twinkling star sparkles that scale and rotate, with a static accent under reduced motion.

- id: `sparkles-text`
- type: primitive
- category: Text and code
- tags: primitive, adapted
- docs: https://glinui.com/docs/components/radix/sparkles-text
- markdown: https://glinui.com/md/sparkles-text.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add sparkles-text
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/sparkles-text.json
```

Package:

```bash
npm install @glinui/ui @glinui/motion @glinui/tokens
```

## Import

```tsx
import { MAX_SPARKLES, SparklesText, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider } from "@glinui/ui"
```

## Usage

Adapted from Sparkles Text by Magic UI (MIT).

Improvements: no motion dependency (Web Animations API), sparkles are created after mount so there is no hydration mismatch from Math.random, a fixed pool re-rolls position in place instead of replacing DOM every 100ms, positions use logical inline-start so RTL mirrors, and the count is capped.

Engines: the `engine` prop is not applicable. Continuous particle twinkle in css keyframes; no entrance to hand to an engine.

```tsx
import { Button, SparklesText } from "@glinui/ui"

export function Demo() {
  return (
    <div className="flex flex-col items-center gap-3 p-8 text-center">
      <SparklesText as="h2" className="text-4xl font-bold tracking-tight">Glin UI Pro</SparklesText>
      <p className="text-sm text-[var(--color-muted)]">Lifetime access to every template.</p>
      <Button>Unlock access</Button>
    </div>
  )
}
```

### Custom colors and count

Any CSS color works, including tokens.

```tsx
import { SparklesText } from "@glinui/ui"

export function Demo() {
  return (
    <SparklesText
      sparklesCount={16}
      colors={{ first: "var(--color-signal-live)", second: "var(--color-accent)" }}
    >
      Shipped
    </SparklesText>
  )
}
```

## Props

### SparklesTextProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as?` | `"div" \| "span" \| "p" \| "h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6"` | `"div"` | Element to render. |
| `children` | `React.ReactNode` |  |  |
| `colors?` | `SparklesTextColors` | `DEFAULT_COLORS` | Sparkle colors. Any CSS color, defaults to Glin tokens. |
| `sparklesCount?` | `number` | `10` | Number of sparkles alive at once. Capped at 24. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- The text is real DOM text and is read normally.
- Every sparkle is a decorative svg with aria-hidden and is pointer-events none.
- No flashing: sparkles scale and fade over about one second each.

ARIA:

- `aria-hidden` on every sparkle

- Reduced motion: With prefers-reduced-motion or motion level none or subtle, the animated pool is replaced by two static stars.

## Provenance

Adapted from Magic UI (MIT, Copyright (c) Magic UI). Upstream: https://magicui.design/docs/components/sparkles-text. Restyled to Glin tokens with accessibility and reduced motion review. Keep the attribution when you copy this component.

---

# Gradient Text

> Flowing gradient or shine sweep text, optionally inside a solid or glass pill badge.

- id: `gradient-text`
- type: primitive
- category: Text and code
- tags: primitive, adapted
- docs: https://glinui.com/docs/components/radix/gradient-text
- markdown: https://glinui.com/md/gradient-text.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add gradient-text
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/gradient-text.json
```

Package:

```bash
npm install @glinui/ui @glinui/motion @glinui/tokens
```

## Import

```tsx
import { GradientText, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider, SURFACE_VARIANTS, SURFACE_TONES, SURFACE_ELEVATIONS, SURFACE_VARIANT_ALIASES } from "@glinui/ui"
```

## Usage

Adapted from Animated Gradient Text and Animated Shiny Text by Magic UI (MIT).

Improvements: colors come from tokens, the badge wrapper ships with solid and glass surfaces, forced-colors fallback, and the sweep is a Web Animations API loop with no global keyframes. Not to be confused with Animated Gradient, which is a background.

A shine badge and a flowing gradient phrase inside a headline on a dark section.

```tsx
import { ArrowRight } from "@phosphor-icons/react"
import { Button, GradientText, Text } from "@glinui/ui"

export function Announcement() {
  return (
    <section data-glin-theme="dark" className="relative isolate flex min-h-[22rem] w-full flex-col items-center justify-center gap-5 overflow-hidden rounded-xl bg-[var(--surface-0)] px-6 py-14 text-center">
      <GradientText badge effect="shine">Now in public beta</GradientText>
      <h1 className="max-w-3xl text-4xl font-semibold tracking-tight text-[var(--color-foreground)] sm:text-6xl">
        Design systems that <GradientText>ship themselves</GradientText>
      </h1>
      <Text size="lg" variant="muted" className="max-w-xl">Sync tokens from Figma, open a pull request with the diff and publish a versioned package, all from one workflow.</Text>
      <div className="flex flex-wrap justify-center gap-3">
        <Button size="lg" trailingIcon={<ArrowRight aria-hidden weight="bold" />}>Join the beta</Button>
        <Button size="lg" variant="outline">Watch the demo</Button>
      </div>
    </section>
  )
}
```

### Effects and badges

Flow and shine effects, custom colors, and badge surfaces.

```tsx
import { GradientText } from "@glinui/ui"

export function GradientVariants() {
  return (
    <div data-glin-theme="dark" className="flex w-full flex-col items-center gap-4 rounded-xl bg-[var(--surface-0)] p-8">
      <GradientText className="text-4xl font-semibold">Flow effect</GradientText>
      <GradientText effect="shine" className="text-4xl font-semibold">Shine effect</GradientText>
      <GradientText from="#38bdf8" to="#a78bfa" className="text-4xl font-semibold">Custom colors</GradientText>
      <div className="flex flex-wrap items-center justify-center gap-3">
        <GradientText badge>Badge</GradientText>
        <GradientText badge variant="outline">Outline badge</GradientText>
        <GradientText badge variant="glass">Glass badge</GradientText>
      </div>
    </div>
  )
}
```

## Props

### GradientTextProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `badge?` | `boolean` | `false` | Wrap the text in a pill badge. `variant` styles the pill surface. |
| `effect?` | `"flow" \| "shine"` | `"flow"` | `flow` slides a looping two color gradient, `shine` sweeps a glint over muted text. |
| `from?` | `string` |  | Gradient start color (flow) or text color (shine). Any CSS color, defaults to Glin tokens. |
| `speed?` | `number` | `1` | Animation speed multiplier. 1 is a 6 second loop for flow, 3 seconds for shine. |
| `to?` | `string` |  | Gradient end color (flow) or glint color (shine). |
| `variant?` | `SurfaceVariant \| "default"` |  | Badge surface (with `badge`). Omit for the ambient design style (glinr by default). Vocabulary: glinr, solid, plain, soft, outline, ghost... |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`.

## Accessibility

- Plain inline text, fully selectable and readable.
- Under forced colors (Windows high contrast) the clip gradient is dropped and the text uses CanvasText, so it never disappears.
- Keep contrast in mind: pick from and to colors that pass 3:1 against the background for large text.
- Reduced motion: With prefers-reduced-motion or motion level none or subtle, the gradient is rendered static, with no sweep.

## Provenance

Adapted from Magic UI (MIT, Copyright (c) Magic UI). Upstream: https://magicui.design/docs/components/animated-gradient-text. Restyled to Glin tokens with accessibility and reduced motion review. Keep the attribution when you copy this component.

---

# Gooey Text Reveal

> Heading whose words melt in through a shared SVG goo filter, or morph between phrases.

- id: `gooey-text-reveal`
- type: primitive
- category: Text and code
- tags: primitive
- docs: https://glinui.com/docs/components/radix/gooey-text-reveal
- markdown: https://glinui.com/md/gooey-text-reveal.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add gooey-text-reveal
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/gooey-text-reveal.json
```

Package:

```bash
npm install @glinui/ui @glinui/motion @glinui/tokens
```

## Import

```tsx
import { GooeyTextReveal, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider } from "@glinui/ui"
```

## Usage

Our own design, written from a behavior spec. One SVG filter (a small gaussian blur plus an alpha contrast matrix) is shared by the whole stage, and each word fades and blurs in with a staggered delay, so the soft edges merge like liquid before settling.

The filter is attached only while an animation runs and is removed afterwards, so settled type is always crisp. Every instance gets its own filter id from `useId`.

Pass an array to `text` to morph between phrases in a loop (the loop pauses offscreen and in hidden tabs). SVG filters on large HTML text cost GPU time: keep it to headings and avoid several large instances in the viewport at once. Safari renders CSS filters that reference SVG filters on HTML but can soften text mid animation, which is expected.

The headline melts in when it scrolls into view.

```tsx
import { GooeyTextReveal } from "@glinui/ui"

export function Demo() {
  return <GooeyTextReveal as="h2" text="Interfaces that melt into place" className="text-5xl" />
}
```

### Variants

Type treatments for each style.

```tsx
<GooeyTextReveal variant="plain" trigger="mount" text="Liquid type" />
```

### States

Morph between phrases, or tune the blob size and stagger.

```tsx
<GooeyTextReveal text={["Design", "Build", "Ship"]} />
<GooeyTextReveal text="Bigger blobs" blur={20} stagger={160} />
```

## Props

### GooeyTextRevealProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as?` | `GooeyTag` | `"h2"` | Element to render. |
| `blur?` | `number` | `12` | Blur radius in pixels at the start of a reveal. Larger values give fatter blobs. |
| `duration?` | `number` | `900` | Duration of one word reveal or one morph in milliseconds. |
| `hold?` | `number` | `2200` | Time each phrase rests before the next morph, in milliseconds (morph mode). |
| `once?` | `boolean` | `true` | Reveal once (true) or replay every time the text re-enters the viewport (reveal mode, trigger view). |
| `stagger?` | `number` | `90` | Delay between words in milliseconds (reveal mode). |
| `text` | `string \| string[]` |  | A string reveals word by word with a liquid edge. An array of two or more strings morphs from one to the next in a loop, like a droplet c... |
| `trigger?` | `"mount" \| "view"` | `"view"` | Start on mount or when scrolled into view (reveal mode). |
| `variant?` | `"default" \| "plain" \| "glass"` | `"default"` | Variant option from gooeyTextRevealVariants. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`, `plain`, `glass`.

## Accessibility

- The full text is the element's accessible name through `aria-label`; the animated words and the SVG are `aria-hidden`.
- Array text is announced as a comma separated list of every phrase.
- The heading level is yours to choose with `as`.
- Animation pauses offscreen and while the tab is hidden.

ARIA:

- `aria-label` on the root with the full text
- `aria-hidden="true"` on the stage and the filter SVG

- Reduced motion: Motion subtle swaps the goo for a plain opacity fade. Under motion none or prefers-reduced-motion the component renders its static frame. The final text is shown with no filter.

---

# Spinning Text

> Text laid out on a rotating circle with an accessible name and pause on hover.

- id: `spinning-text`
- type: primitive
- category: Text and code
- tags: primitive, adapted
- docs: https://glinui.com/docs/components/radix/spinning-text
- markdown: https://glinui.com/md/spinning-text.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add spinning-text
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/spinning-text.json
```

Package:

```bash
npm install @glinui/ui @glinui/motion @glinui/tokens
```

## Import

```tsx
import { SpinningText, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider } from "@glinui/ui"
```

## Usage

Adapted from Spinning Text by Motion Primitives (MIT). Modified: motion/react removed (the ring turns through the Web Animations API), per-glyph angle is a CSS variable, the string is the accessible name of a `role="img"` wrapper, and RTL mirrors the glyph order and spin direction.

Improvement over the original: pause on hover or focus, pause offscreen and in hidden tabs, static ring at motion none, no inline style attributes.

End the string with a separator and a space so the loop reads as a ring: `"open source * made to be owned * "`.

A rotating seal. Hover to pause.

```tsx
import { SpinningText } from "@glinui/ui"

<SpinningText pauseOnHover>{"open source * made to be owned * "}</SpinningText>
```

### Variants

Type treatments.

```tsx
<SpinningText variant="glass">{"glass * glass * "}</SpinningText>
```

### States

Speed, direction and ring size.

```tsx
<SpinningText duration={6} reverse radius={4} fontSize={0.7}>...</SpinningText>
```

## Props

### SpinningTextProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `string` |  | The string laid out on the ring. It becomes the accessible name. |
| `duration?` | `number` | `10` | Seconds per full turn. |
| `fontSize?` | `number` | `1` | Glyph size in rem. |
| `pauseOnHover?` | `boolean` | `false` | Pause the rotation while hovered or focused within. |
| `radius?` | `number` | `5` | Ring radius in ch units. |
| `reverse?` | `boolean` | `false` | Spin counter-clockwise. In RTL documents the default direction is mirrored. |
| `variant?` | `"default" \| "plain" \| "glass"` | `"default"` | Variant option from spinningTextVariants. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`, `plain`, `glass`.

## Accessibility

- The wrapper is `role="img"` with `aria-label` set to the full string; the individual glyphs are `aria-hidden`.
- Decorative by default. Pair it with a visible heading if the text carries meaning.
- Never traps focus or intercepts pointer events beyond the optional hover pause.

ARIA:

- `role="img"` with `aria-label`
- `aria-hidden="true"` on the glyph ring

- Reduced motion: The ring only turns at motion level full. Under motion none or prefers-reduced-motion the component renders its static frame. Glyphs stay placed on the circle.

## Provenance

Adapted from Motion Primitives (MIT, Copyright (c) 2024 ibelick). Upstream: https://motion-primitives.com/docs/spinning-text. Restyled to Glin tokens with accessibility and reduced motion review. Keep the attribution when you copy this component.

---

# Code

> Inline code element for commands, snippets, and tokenized literals.

- id: `code`
- type: primitive
- category: Text and code
- tags: primitive
- docs: https://glinui.com/docs/components/radix/code
- markdown: https://glinui.com/md/code.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add code
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/code.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Code, LIFT_RING, LIFT_MONO_LABEL, PLAIN_CONTAINER, SURFACE_VARIANTS, SURFACE_TONES, SURFACE_ELEVATIONS, SURFACE_VARIANT_ALIASES } from "@glinui/ui"
```

## Usage

Code marks identifiers, values and commands inside prose. The block variant sets a one line command apart.

```tsx
import { Code, Heading, Text } from "@glinui/ui"

export function RetryDocs() {
  return (
    <div className="flex w-full max-w-2xl flex-col gap-4 rounded-2xl border border-[var(--line-soft)] bg-[var(--surface-1)] p-6 text-left">
      <Heading level={2} size="sm">Configure retries</Heading>
      <Text>
        Set <Code>maxRetries</Code> on the client to control how often a failed request is repeated. The default is <Code tone="accent">3</Code>, and
        requests that return <Code>4xx</Code> are never retried.
      </Text>
      <Text variant="muted">
        Override it per call with <Code variant="outline">client.get(url, {"{ maxRetries: 0 }"})</Code> or set the <Code variant="soft">ACME_MAX_RETRIES</Code> variable in your environment.
      </Text>
      <Code variant="block" className="block">pnpm acme config set maxRetries 5</Code>
    </div>
  )
}
```

### Variants and tones

Surface variants plus tones for status values.

```tsx
import { Code } from "@glinui/ui"

export function CodeVariants() {
  return (
    <div className="flex w-full flex-wrap items-center justify-center gap-3 rounded-xl border border-[var(--line-soft)] bg-[var(--surface-1)] p-6">
      {(["glinr", "plain", "soft", "outline", "ghost", "solid"] as const).map((variant) => (
        <Code key={variant} variant={variant}>{variant}</Code>
      ))}
      {(["accent", "success", "warning", "danger"] as const).map((tone) => (
        <Code key={tone} variant="soft" tone={tone}>{tone}</Code>
      ))}
    </div>
  )
}
```

### Variants

The `variant` prop adjusts the surface behind the code token, filled, glass-blurred, border-only, or fully transparent.

```tsx
import { Code } from "@glinui/ui"

export function CodeVariantDemo() {
  return (
    <div className="flex flex-wrap gap-3">
      <Code variant="default">default</Code>
      <Code variant="glass">glass</Code>
      <Code variant="outline">outline</Code>
      <Code variant="ghost">ghost</Code>
    </div>
  )
}
```

## Props

### CodeProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size?` | `"sm" \| "md" \| "lg"` |  |  |
| `tone?` | `SurfaceTone` |  |  |
| `variant?` | `SurfaceVariant \| "block" \| "default" \| "primary" \| "secondary" \| "destructive" \| "success" \| "warnin...` |  | Visual variant. Omit for the ambient design style (glinr by default). `block` renders a full width code well: inset well under glinr, fla... |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `block`, `default`, `primary`, `secondary`, `destructive`, `success`, `warning`, `info`, `raised`, `frosted`.

## Accessibility

- Uses semantic `<code>` element for inline code fragments.
- `Code` renders a native `<code>` element, which assistive technologies announce as a code region.
- Screen readers may vocalize code content differently, keep snippets short and purposeful.
- Do not use `Code` for decorative styling; only wrap content that is genuinely code or a technical literal.
- Ensure sufficient contrast between the code token and the surrounding prose in all variants.
- Reduced motion: No motion-dependent behavior. `Code` is a static inline element with no animation. No reduced-motion considerations apply.

---

# Code Panel

> Raised header bar over an inset code well with tok-k, tok-s, tok-c and tok-f token classes.

- id: `code-panel`
- type: primitive
- category: Text and code
- tags: primitive
- docs: https://glinui.com/docs/components/radix/code-panel
- markdown: https://glinui.com/md/code-panel.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add code-panel
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/code-panel.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { CodePanel, SURFACE_VARIANTS, SURFACE_TONES, SURFACE_ELEVATIONS, SURFACE_VARIANT_ALIASES, STYLE_DEFAULT_VARIANT, GlinProvider, GLIN_MOTIONS } from "@glinui/ui"
```

## Usage

A docs page step: install tabs, then a CodePanel whose header tabs switch between filenames. Copy always matches the visible file.

```tsx
"use client"

import { Fragment, useState } from "react"
import { CodePanel, Heading, InstallCommand, Tabs, TabsContent, TabsList, TabsTrigger, Text, tokens } from "@glinui/ui"

type Part = string | readonly ["k" | "s" | "c" | "f", string]

const layoutLines: Array<readonly Part[]> = [[["k","import"]," { GlinProvider } ",["k","from"]," ",["s","\"@glinui/ui\""]],[["k","import"]," ",["s","\"@glinui/tokens/styles.css\""]],[],[["k","export default function"]," ",["f","RootLayout"],"({ children }) {"],["  ",["k","return"]," ("],["    <html lang=\"en\">"],["      <body>"],["        <GlinProvider>{children}</GlinProvider>"],["      </body>"],["    </html>"],["  )"],["}"]]

const pageLines: Array<readonly Part[]> = [[["k","import"]," { Button } ",["k","from"]," ",["s","\"@glinui/ui\""]],[],[["k","export default function"]," ",["f","Page"],"() {"],["  ",["k","return"]," <Button>Get started</Button>"],["}"]]

const textOf = (lines: Array<readonly Part[]>) =>
  lines.map((line) => line.map((part) => (typeof part === "string" ? part : part[1])).join("")).join("\n")

function Lines({ lines }: { lines: Array<readonly Part[]> }) {
  return (
    <>
      {lines.map((parts, index) => (
        <Fragment key={index}>
          {tokens(...parts)}
          {index < lines.length - 1 ? "\n" : null}
        </Fragment>
      ))}
    </>
  )
}

export function QuickStart() {
  const [file, setFile] = useState("layout")
  return (
    <article className="flex w-full max-w-3xl flex-col gap-6 text-left">
      <div className="flex flex-col gap-2">
        <Text variant="eyebrow">Getting started</Text>
        <Heading level={1} size="h2">Add Glin UI to a Next.js app</Heading>
        <Text variant="muted">Two packages, one import and your first component. It takes about two minutes.</Text>
      </div>
      <Heading level={3} size="sm">1. Install the packages</Heading>
      <InstallCommand packageName="@glinui/ui @glinui/tokens" title="Terminal" />
      <Heading level={3} size="sm">2. Wrap your app and use a component</Heading>
      <Tabs value={file} onValueChange={setFile} asChild>
        <div>
          <CodePanel
            title="app/"
            codeLabel="Example source"
            copyValue={textOf(file === "layout" ? layoutLines : pageLines)}
            tabs={
              <TabsList variant="keys" size="sm" aria-label="Files">
                <TabsTrigger value="layout" variant="keys" size="sm">layout.tsx</TabsTrigger>
                <TabsTrigger value="page" variant="keys" size="sm">page.tsx</TabsTrigger>
              </TabsList>
            }
          >
            <TabsContent value="layout" variant="keys" className="mt-0 p-0" asChild>
              <span><Lines lines={layoutLines} /></span>
            </TabsContent>
            <TabsContent value="page" variant="keys" className="mt-0 p-0" asChild>
              <span><Lines lines={pageLines} /></span>
            </TabsContent>
          </CodePanel>
        </div>
      </Tabs>
    </article>
  )
}
```

### Variants

Glinr raised panel, plain flat block and outline, each with a filename title and copy button.

```tsx
import { CodePanel, tokens } from "@glinui/ui"

const variants = ["glinr", "plain", "outline"] as const

export function PanelVariants() {
  return (
    <div className="grid w-full gap-4 md:grid-cols-3">
      {variants.map((variant) => (
        <CodePanel key={variant} variant={variant} title={`${variant}.ts`} copyValue="const retries = 3" codeLabel={`${variant} sample`}>
          {tokens(["k", "const"], " retries = ", ["f", "3"], "\n", ["c", "// 4xx errors never retry"])}
        </CodePanel>
      ))}
    </div>
  )
}
```

## Props

### CodePanelProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `actions?` | `React.ReactNode` |  | Header slot on the right. When `copyValue` is set a CopyButton is appended. |
| `codeLabel?` | `string` | `"Code"` | Accessible label for the scrollable code region. |
| `copyValue?` | `string` |  | Adds a CopyButton to the header copying this text. |
| `hideHeader?` | `boolean` | `false` | Hide the header bar entirely. |
| `onCopy?` | `(value: string) => void` |  | Called when the built-in CopyButton succeeds. |
| `preClassName?` | `string` |  | Classes for the `pre` element. |
| `tabs?` | `React.ReactNode` |  | Header slot after the title, for example a tab group. |
| `title?` | `React.ReactNode` |  | Header title (usually a file name). |
| `tone?` | `SurfaceTone` |  |  |
| `variant?` | `SurfaceVariant \| "default" \| "raised" \| "frosted"` |  | Visual variant. Omit for the ambient design style: glinr is the canonical raised panel (header strip + inset well), plain is a flat borde... |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`, `raised`, `frosted`.

## Accessibility

- The code well is focusable so keyboard users can scroll it horizontally.
- Token colors rely on the tok-k, tok-s, tok-c and tok-f classes, never on color alone for meaning.

ARIA:

- aria-label on the pre element

- Reduced motion: No motion.

---

# Install Command

> Package manager tabs, a $ prefixed command and a copy button inside a code panel.

- id: `install-command`
- type: primitive
- category: Text and code
- tags: primitive
- docs: https://glinui.com/docs/components/radix/install-command
- markdown: https://glinui.com/md/install-command.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add install-command
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/install-command.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { InstallCommand } from "@glinui/ui"
```

## Usage

Package manager tabs for a package, plus a custom command map for a registry add.

```tsx
import { Heading, InstallCommand, Text } from "@glinui/ui"

export function InstallDocs() {
  return (
    <article className="flex w-full max-w-2xl flex-col gap-4 text-left">
      <Heading level={2} size="sm">Install the CLI</Heading>
      <Text variant="muted">Pick your package manager. The command is copied exactly as shown.</Text>
      <InstallCommand packageName="@acme/cli" title="Terminal" />
      <Text variant="muted">Or add a single component with the registry command.</Text>
      <InstallCommand
        title="Registry"
        commands={{
          pnpm: "pnpm dlx @glinui/cli@latest add button",
          npm: "npx @glinui/cli@latest add button",
          bun: "bunx @glinui/cli@latest add button"
        }}
      />
    </article>
  )
}
```

### Variants

Surface variants of the underlying CodePanel.

```tsx
import { InstallCommand } from "@glinui/ui"

export function InstallVariants() {
  return (
    <div className="grid w-full gap-4 md:grid-cols-2">
      <InstallCommand packageName="zod" variant="glinr" title="glinr" />
      <InstallCommand packageName="zod" variant="plain" title="plain" />
    </div>
  )
}
```

## Props

### InstallCommandProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `commands?` | `Record<string, string>` |  | Custom tab label to full command map. Keys become the tabs, in insertion order. |
| `defaultValue?` | `string` |  | Initial tab when uncontrolled. Defaults to the first tab. |
| `onCopy?` | `(command: string, tab: string) => void` |  | Called after a successful copy with the copied command (without the `$`). |
| `onValueChange?` | `(value: string) => void` |  | Called when the tab changes. |
| `packageName?` | `string` | `"@glinui/ui"` | Package name(s); builds npm / pnpm / yarn / bun commands. Ignored when `commands` is set. |
| `tabsLabel?` | `string` | `"Package manager"` | Accessible name of the tab list. |
| `title?` | `React.ReactNode` |  | Header title. |
| `value?` | `string` |  | Controlled active tab. |
| `variant?` | `CodePanelProps["variant"]` |  | Surface variant of the underlying CodePanel. Omit for the ambient design style (glinr canonical, plain flat block, glass opt-in). |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `variant`.

## Accessibility

- Built on Tabs: arrow keys move between package managers.
- The $ prefix is hidden from assistive technology and from selection.

Keyboard:

| Key | Action |
| --- | --- |
| ArrowLeft / ArrowRight | Move between tabs. |
| Enter / Space | Activate the copy button. |

- Reduced motion: No motion beyond the copy button press.

---

# Terminal

> Terminal window with sequenced typing and output, a full transcript and copy.

- id: `terminal`
- type: primitive
- category: Text and code
- tags: primitive, adapted
- docs: https://glinui.com/docs/components/radix/terminal
- markdown: https://glinui.com/md/terminal.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add terminal
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/terminal.json
```

Package:

```bash
npm install @glinui/ui @glinui/motion @glinui/tokens
```

## Import

```tsx
import { AnimatedSpan, TypingAnimation, Terminal, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider, SURFACE_VARIANTS, SURFACE_TONES } from "@glinui/ui"
```

## Usage

Adapted from Terminal by Magic UI (MIT).

Improvements: no animation library, timers with cleanup and Strict Mode safety, a static first render for SSR and reduced motion, a screen-reader transcript instead of live typing, a built-in copy button, glass variant and tokenised colors.

Engines: this component drives its main animation through the pluggable motion engine. Pass `engine` (css, motion or gsap), wrap a subtree in `MotionEngineProvider`, or set `data-glin-engine` on `<html>`. The css engine is built in and dependency free; motion and gsap are opt-in via `@glinui/motion/register/*`. `motion="none"` renders the final state and `subtle` is opacity only.

Typed command followed by output lines.

```tsx
import { AnimatedSpan, Terminal, TypingAnimation } from "@glinui/ui"

export function Demo() {
  return (
    <Terminal title="~/my-app" className="max-w-xl" startOnView={false}>
      <TypingAnimation duration={40}>pnpm dlx glinui init</TypingAnimation>
      <AnimatedSpan className="text-[var(--color-muted)]">Detected Next.js and Tailwind CSS</AnimatedSpan>
      <AnimatedSpan className="text-[var(--color-muted)]">Wrote glinui.json and theme tokens</AnimatedSpan>
      <TypingAnimation duration={40}>pnpm dlx glinui add button card</TypingAnimation>
      <AnimatedSpan className="text-[var(--color-signal-ok)]">Added 2 components in 1.2s</AnimatedSpan>
    </Terminal>
  )
}
```

### Variants

Every vocabulary variant on the default tone. Omit variant to follow the ambient design style.

```tsx
import { AnimatedSpan, Terminal } from "@glinui/ui"

export function TerminalVariantsDemo() {
  return (
    <div className="grid gap-4 md:grid-cols-2">
      <Terminal variant="glinr" title="glinr" sequence={false} showCopy={false}><AnimatedSpan>$ pnpm add @glinui/ui</AnimatedSpan></Terminal>
      <Terminal variant="solid" title="solid" sequence={false} showCopy={false}><AnimatedSpan>$ pnpm add @glinui/ui</AnimatedSpan></Terminal>
      <Terminal variant="plain" title="plain" sequence={false} showCopy={false}><AnimatedSpan>$ pnpm add @glinui/ui</AnimatedSpan></Terminal>
      <Terminal variant="soft" title="soft" sequence={false} showCopy={false}><AnimatedSpan>$ pnpm add @glinui/ui</AnimatedSpan></Terminal>
      <Terminal variant="outline" title="outline" sequence={false} showCopy={false}><AnimatedSpan>$ pnpm add @glinui/ui</AnimatedSpan></Terminal>
      <Terminal variant="ghost" title="ghost" sequence={false} showCopy={false}><AnimatedSpan>$ pnpm add @glinui/ui</AnimatedSpan></Terminal>
      <Terminal variant="gradient" title="gradient" sequence={false} showCopy={false}><AnimatedSpan>$ pnpm add @glinui/ui</AnimatedSpan></Terminal>
    </div>
  )
}
```

### No sequence

Every line starts on its own delay.

```tsx
<Terminal sequence={false} showCopy={false}>
  <AnimatedSpan delay={200}>one</AnimatedSpan>
  <AnimatedSpan delay={900}>two</AnimatedSpan>
</Terminal>
```

## Props

### AnimatedSpanProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `delay?` | `number` | `0` | Milliseconds to wait after this line's turn before it appears. |

### TerminalProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `copyValue?` | `string` |  | Text copied by the button. Defaults to the full transcript. |
| `engine?` | `EngineName` |  | Engine override: `css` (default), `motion`, `gsap` or a registered custom engine. |
| `motion?` | `MotionLevel` |  | Motion override. `none` renders the static final state, `subtle` is opacity only. |
| `outputClassName?` | `string` |  | Class for the scrolling output area. |
| `sequence?` | `boolean` | `true` | Reveal animated children one after another. |
| `showCopy?` | `boolean` | `true` | Show the copy button. |
| `startOnView?` | `boolean` | `true` | Wait until the terminal is scrolled into view before playing. |
| `title?` | `string` |  | Window title in the chrome. |
| `tone?` | `SurfaceTone` |  |  |
| `variant?` | `SurfaceVariant \| "default" \| "raised" \| "frosted"` |  | Visual variant. Omit for the ambient design style (glinr: lift shell, raised chrome strip, inset output well; plain: flat bordered termin... |

### TypingAnimationProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as?` | `"span" \| "div" \| "p"` | `"span"` |  |
| `children` | `string` |  | Text to type. Must be a string. |
| `delay?` | `number` | `0` | Milliseconds to wait after this line's turn before typing starts. |
| `duration?` | `number` | `60` | Milliseconds per character. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`, `raised`, `frosted`.

## Accessibility

- The first render, SSR and reduced motion all show the full final text.
- While animating, the visual layer is aria-hidden and a screen-reader-only transcript carries the full text, so nothing is announced character by character.
- The copy button announces the result through a polite live region.

Keyboard:

| Key | Action |
| --- | --- |
| Tab | Reaches the copy button; the output area has no extra tab stops. |

ARIA:

- `role=group` with `aria-label`
- `aria-live=off` on the animated layer
- Copy status is `role=status`

- Reduced motion: Full motion types commands and fades lines in. Subtle fades lines in without typing. None, or prefers-reduced-motion, renders the full transcript at once. Timers are cleared on unmount.

## Provenance

Adapted from Magic UI (MIT, Copyright (c) Magic UI). Upstream: https://magicui.design/docs/components/terminal. Restyled to Glin tokens with accessibility and reduced motion review. Keep the attribution when you copy this component.

---

# Kbd

> Keyboard keycap primitive for shortcuts and key hints.

- id: `kbd`
- type: primitive
- category: Text and code
- tags: primitive
- docs: https://glinui.com/docs/components/radix/kbd
- markdown: https://glinui.com/md/kbd.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add kbd
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/kbd.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Kbd, SURFACE_VARIANTS, SURFACE_TONES, SURFACE_ELEVATIONS, SURFACE_VARIANT_ALIASES, STYLE_DEFAULT_VARIANT, GlinProvider, GLIN_MOTIONS } from "@glinui/ui"
```

## Usage

A shortcut cheat sheet grouped by task.

```tsx
import { Card, CardContent, CardDescription, CardHeader, CardTitle, Kbd } from "@glinui/ui"

export function Demo() {
  const groups = [
    { title: "Navigation", rows: [["Open command palette", ["Ctrl", "K"]], ["Go to dashboard", ["G", "D"]], ["Toggle sidebar", ["Ctrl", "B"]]] },
    { title: "Editing", rows: [["Save", ["Ctrl", "S"]], ["Undo", ["Ctrl", "Z"]], ["Duplicate line", ["Shift", "Alt", "Down"]]] }
  ] as const
  return (
    <Card className="w-full max-w-lg">
      <CardHeader>
        <CardTitle>Keyboard shortcuts</CardTitle>
        <CardDescription>Press ? anywhere to open this list.</CardDescription>
      </CardHeader>
      <CardContent className="flex flex-col gap-5">
        {groups.map((group) => (
          <section key={group.title} aria-label={group.title} className="flex flex-col gap-1">
            <h4 className="text-xs font-semibold uppercase tracking-wider text-[var(--color-muted)]">{group.title}</h4>
            {group.rows.map(([label, keys]) => (
              <div key={label} className="flex items-center justify-between gap-4 border-b border-[var(--line-soft)] py-2 text-sm last:border-b-0">
                <span>{label}</span>
                <span className="flex items-center gap-1">
                  {keys.map((key) => (
                    <Kbd key={key}>{key}</Kbd>
                  ))}
                </span>
              </div>
            ))}
          </section>
        ))}
      </CardContent>
    </Card>
  )
}
```

### Inline hints

A search field hint, keys in running text and three sizes.

```tsx
import { MagnifyingGlass } from "@phosphor-icons/react"
import { Input, Kbd } from "@glinui/ui"

export function Demo() {
  return (
    <div className="flex w-full max-w-md flex-col gap-4">
      <label className="relative block">
        <span className="sr-only">Search</span>
        <MagnifyingGlass aria-hidden className="pointer-events-none absolute left-3 top-1/2 size-4 -translate-y-1/2 text-[var(--color-muted)]" />
        <Input placeholder="Search docs" className="pl-9 pr-16" />
        <span className="pointer-events-none absolute right-3 top-1/2 flex -translate-y-1/2 items-center gap-1">
          <Kbd size="sm">Ctrl</Kbd>
          <Kbd size="sm">K</Kbd>
        </span>
      </label>
      <p className="text-sm text-[var(--color-muted)]">
        Press <Kbd size="sm">Esc</Kbd> to close, <Kbd size="sm">Enter</Kbd> to open the first result.
      </p>
      <div className="flex flex-wrap items-center gap-3">
        <Kbd size="sm">sm</Kbd>
        <Kbd size="md">md</Kbd>
        <Kbd size="lg">lg</Kbd>
      </div>
    </div>
  )
}
```

### Shortcuts

Combine multiple `Kbd` elements with a `+` separator to represent compound key shortcuts.

```tsx
import { Kbd } from "@glinui/ui"

export function KbdShortcutDemo() {
  return (
    <div className="flex items-center gap-1">
      <Kbd>⌘</Kbd>
      <span className="text-neutral-400">+</span>
      <Kbd>K</Kbd>
    </div>
  )
}
```

## Props

### KbdProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size?` | `"sm" \| "md" \| "lg"` |  |  |
| `tone?` | `SurfaceTone` |  |  |
| `variant?` | `SurfaceVariant \| "default" \| "primary" \| "secondary" \| "destructive" \| "success" \| "warning" \| "info...` |  | Visual variant. Omit for the ambient design style (glinr: tactile raised key). |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`, `primary`, `secondary`, `destructive`, `success`, `warning`, `info`, `raised`, `frosted`.

## Accessibility

- Uses semantic `<kbd>` element for keyboard shortcuts.
- `Kbd` renders a native `<kbd>` element which is recognized by assistive technologies as denoting keyboard input.
- Screen readers will announce the content of each `<kbd>` element; use descriptive key names or Unicode symbols that read naturally.
- Avoid using `<Kbd>` purely for styling, reserve it for actual keyboard key references.
- Reduced motion: No motion-dependent behavior. `Kbd` is a static element with no animation. It is unaffected by `prefers-reduced-motion`.

---

# Animated Gradient

> Animated color-shifting gradient background with warm, cool, aurora, and glass presets.

- id: `animated-gradient`
- type: signature
- category: Backgrounds
- tags: signature
- docs: https://glinui.com/docs/components/animated-gradient
- markdown: https://glinui.com/md/animated-gradient.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add animated-gradient
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/animated-gradient.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { AnimatedGradient } from "@glinui/ui"
```

## Usage

```tsx
import { AnimatedGradient, Button, Heading, Text } from "@glinui/ui"

export function TrialBanner() {
  return (
    <AnimatedGradient data-glin-theme="dark" variant="cool" className="flex w-full flex-col items-start justify-between gap-4 rounded-2xl p-6 text-left sm:flex-row sm:items-center">
      <div className="flex flex-col gap-1">
        <Heading level={2} size="md">Your trial ends in 3 days</Heading>
        <Text variant="muted" className="text-[var(--color-foreground)]">Keep your projects, history and team seats by picking a plan today.</Text>
      </div>
      <div className="flex shrink-0 gap-3"><Button variant="solid">Choose a plan</Button><Button variant="outline">Remind me later</Button></div>
    </AnimatedGradient>
  )
}
```

```tsx
import { Check } from "@phosphor-icons/react"
import { AnimatedGradient, Badge, Button, Heading, Text } from "@glinui/ui"

const plans = [
  { name: "Starter", price: "$0", note: "For side projects", items: ["3 projects", "Community support"], featured: false },
  { name: "Pro", price: "$24", note: "For growing teams", items: ["Unlimited projects", "Priority support", "Audit log export"], featured: true },
  { name: "Scale", price: "$99", note: "For large orgs", items: ["SSO and SCIM", "99.99% uptime SLA"], featured: false }
]

const card = "flex flex-col gap-4 rounded-2xl border border-[var(--line-soft)] bg-[var(--surface-1)] p-6 text-left"

export function Pricing() {
  return (
    <section aria-label="Pricing" className="grid w-full gap-4 md:grid-cols-3">
      {plans.map((plan) => {
        const body = (
          <>
            <div className="flex items-center justify-between">
              <Heading level={3} size="sm">{plan.name}</Heading>
              {plan.featured ? <Badge tone="accent" variant="solid">Most popular</Badge> : null}
            </div>
            <p className="flex items-baseline gap-1"><span className="text-4xl font-semibold tabular-nums text-[var(--color-foreground)]">{plan.price}</span><span className="text-sm text-[var(--color-muted)]">/ seat</span></p>
            <Text size="sm" variant="muted">{plan.note}</Text>
            <ul className="flex flex-col gap-2 text-sm text-[var(--color-foreground)]">
              {plan.items.map((item) => (
                <li key={item} className="flex items-center gap-2"><Check aria-hidden weight="bold" className="size-4 shrink-0" />{item}</li>
              ))}
            </ul>
            <Button variant={plan.featured ? "solid" : "outline"} className="mt-auto w-full">{plan.featured ? "Start free trial" : "Choose plan"}</Button>
          </>
        )
        return plan.featured ? (
          <AnimatedGradient key={plan.name} variant="aurora" data-glin-theme="dark" className={`${card} border-transparent`}>{body}</AnimatedGradient>
        ) : (
          <div key={plan.name} className={card}>{body}</div>
        )
      })}
    </section>
  )
}
```

```tsx
import { AnimatedGradient } from "@glinui/ui"

export function AnimatedGradientVariantsDemo() {
  return (
    <div className="grid grid-cols-2 gap-4">
      <AnimatedGradient variant="warm" className="flex h-32 items-center justify-center rounded-xl">
        <span className="text-sm font-medium">Warm</span>
      </AnimatedGradient>
      <AnimatedGradient variant="cool" className="flex h-32 items-center justify-center rounded-xl">
        <span className="text-sm font-medium">Cool</span>
      </AnimatedGradient>
      <AnimatedGradient variant="aurora" className="flex h-32 items-center justify-center rounded-xl">
        <span className="text-sm font-medium text-[var(--color-foreground)]">Aurora</span>
      </AnimatedGradient>
      <AnimatedGradient variant="glass" className="flex h-32 items-center justify-center rounded-xl">
        <span className="text-sm font-medium">Glass</span>
      </AnimatedGradient>
    </div>
  )
}
```

## Props

### AnimatedGradientProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `duration?` | `number` | `6` |  |
| `variant?` | `"default" \| "glass" \| "warm" \| "cool" \| "aurora"` | `"default"` | Variant option from gradientVariants. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`, `glass`, `warm`, `cool`, `aurora`.

## Accessibility

- Decorative background container, content inside remains accessible.
- No interactive elements in the gradient itself.
- Reduced motion: Animation uses `motion-reduce:animate-none`. Under `prefers-reduced-motion`, the gradient renders as a static background.

---

# Gradient Mesh

> Generative mesh gradient background using overlapping radial gradients.

- id: `gradient-mesh`
- type: signature
- category: Backgrounds
- tags: signature
- docs: https://glinui.com/docs/components/gradient-mesh
- markdown: https://glinui.com/md/gradient-mesh.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add gradient-mesh
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/gradient-mesh.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { GradientMesh } from "@glinui/ui"
```

## Usage

```tsx
import { GradientMesh, Badge, Button, Heading, Text } from "@glinui/ui"

export function Hero() {
  return (
    <section data-glin-theme="dark" className="relative isolate flex min-h-[26rem] w-full flex-col items-center justify-center gap-8 overflow-hidden rounded-xl bg-[var(--surface-0)] px-4 py-14 text-center sm:px-8">
      <GradientMesh intensity={0.5} />
      <div className="relative z-10 flex max-w-2xl flex-col items-center gap-4">
        <Badge tone="accent" variant="soft">Dashboards 2.0</Badge>
        <Heading level={1} size="display">Answers from your data, without the SQL</Heading>
        <Text size="lg" variant="muted" className="max-w-xl">
          Connect a warehouse, ask in plain language and pin the result to a dashboard your whole team can open.
        </Text>
        <div className="flex flex-wrap items-center justify-center gap-3 pt-2">
          <Button size="lg">Connect a source</Button>
          <Button size="lg" variant="outline">See a sample</Button>
        </div>
      </div>
      <div className="relative z-10 flex flex-col items-center gap-3">
        <Text size="sm" variant="muted">Works with</Text>
        <ul className="flex flex-wrap items-center justify-center gap-x-6 gap-y-2 text-[var(--color-foreground)]">
          {/* Your partner or customer logos go here */}
          <li className="text-sm font-medium">Vercel</li>
          <li className="text-sm font-medium">GitHub</li>
          <li className="text-sm font-medium">Cloudflare</li>
          <li className="text-sm font-medium">Astro</li>
        </ul>
      </div>
    </section>
  )
}
```

```tsx
import { GradientMesh } from "@glinui/ui"

export function Variants() {
  return (
    <div data-glin-theme="dark" className="grid w-full gap-3 sm:grid-cols-3">
      <div className="relative isolate flex h-44 items-end overflow-hidden rounded-xl bg-[var(--surface-0)] p-3">
        <GradientMesh intensity={0.6} />
        <span className="relative z-10 rounded-full bg-black/70 px-2.5 py-1 text-xs font-medium text-white">Default</span>
      </div>
      <div className="relative isolate flex h-44 items-end overflow-hidden rounded-xl bg-[var(--surface-0)] p-3">
        <GradientMesh colors={["#f43f5e", "#f97316", "#eab308"]} intensity={0.5} />
        <span className="relative z-10 rounded-full bg-black/70 px-2.5 py-1 text-xs font-medium text-white">Warm</span>
      </div>
      <div className="relative isolate flex h-44 items-end overflow-hidden rounded-xl bg-[var(--surface-0)] p-3">
        <GradientMesh duration={24} blur={120} intensity={0.5} />
        <span className="relative z-10 rounded-full bg-black/70 px-2.5 py-1 text-xs font-medium text-white">Slow and soft</span>
      </div>
    </div>
  )
}
```

```tsx
import { GradientMesh, Button, Heading, Input, Label, Text } from "@glinui/ui"

export function SignIn() {
  return (
    <section data-glin-theme="dark" className="relative isolate flex min-h-[26rem] w-full items-center justify-center overflow-hidden rounded-xl bg-[var(--surface-0)] px-4 py-10">
      <GradientMesh intensity={0.5} />
      <form className="relative z-10 flex w-full max-w-sm flex-col gap-4 rounded-2xl border border-[var(--line-soft)] bg-[var(--surface-1)] p-6 text-left [box-shadow:var(--shadow-lg)]">
        <div className="flex flex-col gap-1">
          <Heading level={2} size="sm">Sign in to Northwind</Heading>
          <Text size="sm" variant="muted">Use your work email to continue.</Text>
        </div>
        <div className="flex flex-col gap-1.5">
          <Label htmlFor="email">Work email</Label>
          <Input id="email" type="email" autoComplete="email" placeholder="you@company.com" />
        </div>
        <div className="flex flex-col gap-1.5">
          <Label htmlFor="password">Password</Label>
          <Input id="password" type="password" autoComplete="current-password" placeholder="At least 12 characters" />
        </div>
        <Button type="submit" className="w-full">Continue</Button>
      </form>
    </section>
  )
}
```

## Props

### GradientMeshProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `blur?` | `number` | `60` | Blur intensity in px |
| `colors?` | `string[]` | `["var(--color-accent)", "var(--tone-d...` | Gradient color stops. Defaults come from theme tokens. |
| `duration?` | `number` | `10` | Animation duration in seconds |
| `intensity?` | `number` | `0.6` | Overall intensity/opacity (0-1) |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Renders with `aria-hidden`, invisible to assistive technologies.
- Purely decorative; carries no semantic meaning.
- Reduced motion: Mesh animations are paused via `motion-reduce:[animation:none]`. Static gradients remain visible.

---

# Aurora Background

> Animated gradient mesh backdrop with floating blurred blobs.

- id: `aurora-background`
- type: signature
- category: Backgrounds
- tags: signature
- docs: https://glinui.com/docs/components/aurora-background
- markdown: https://glinui.com/md/aurora-background.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add aurora-background
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/aurora-background.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { AuroraBackground } from "@glinui/ui"
```

## Usage

```tsx
import { AuroraBackground, Badge, Button, Heading, Text } from "@glinui/ui"

export function Hero() {
  return (
    <section data-glin-theme="dark" className="relative isolate flex min-h-[26rem] w-full flex-col items-center justify-center gap-8 overflow-hidden rounded-xl bg-[var(--surface-0)] px-4 py-14 text-center sm:px-8">
      <AuroraBackground intensity={0.55} />
      <div className="relative z-10 flex max-w-2xl flex-col items-center gap-4">
        <Badge tone="accent" variant="soft">Branch previews are live</Badge>
        <Heading level={1} size="display">Ship every branch to a live URL</Heading>
        <Text size="lg" variant="muted" className="max-w-xl">
          Push to Git and get a shareable preview in under a minute, with logs, rollbacks and per-branch environment variables.
        </Text>
        <div className="flex flex-wrap items-center justify-center gap-3 pt-2">
          <Button size="lg">Start deploying</Button>
          <Button size="lg" variant="outline">Read the docs</Button>
        </div>
      </div>
      <div className="relative z-10 flex flex-col items-center gap-3">
        <Text size="sm" variant="muted">Works with</Text>
        <ul className="flex flex-wrap items-center justify-center gap-x-6 gap-y-2 text-[var(--color-foreground)]">
          {/* Your partner or customer logos go here */}
          <li className="text-sm font-medium">Vercel</li>
          <li className="text-sm font-medium">GitHub</li>
          <li className="text-sm font-medium">Cloudflare</li>
          <li className="text-sm font-medium">Astro</li>
        </ul>
      </div>
    </section>
  )
}
```

```tsx
import { AuroraBackground } from "@glinui/ui"

export function Variants() {
  return (
    <div data-glin-theme="dark" className="grid w-full gap-3 sm:grid-cols-3">
      <div className="relative isolate flex h-44 items-end overflow-hidden rounded-xl bg-[var(--surface-0)] p-3">
        <AuroraBackground intensity={0.6} />
        <span className="relative z-10 rounded-full bg-black/70 px-2.5 py-1 text-xs font-medium text-white">Default</span>
      </div>
      <div className="relative isolate flex h-44 items-end overflow-hidden rounded-xl bg-[var(--surface-0)] p-3">
        <AuroraBackground colors={["#06b6d4", "#3b82f6", "#8b5cf6"]} intensity={0.6} />
        <span className="relative z-10 rounded-full bg-black/70 px-2.5 py-1 text-xs font-medium text-white">Cool tones</span>
      </div>
      <div className="relative isolate flex h-44 items-end overflow-hidden rounded-xl bg-[var(--surface-0)] p-3">
        <AuroraBackground blobCount={5} duration={12} blur={100} intensity={0.6} />
        <span className="relative z-10 rounded-full bg-black/70 px-2.5 py-1 text-xs font-medium text-white">Dense</span>
      </div>
    </div>
  )
}
```

```tsx
import { AuroraBackground, Button, Heading, Input, Label, Text } from "@glinui/ui"

export function SignIn() {
  return (
    <section data-glin-theme="dark" className="relative isolate flex min-h-[26rem] w-full items-center justify-center overflow-hidden rounded-xl bg-[var(--surface-0)] px-4 py-10">
      <AuroraBackground intensity={0.55} />
      <form className="relative z-10 flex w-full max-w-sm flex-col gap-4 rounded-2xl border border-[var(--line-soft)] bg-[var(--surface-1)] p-6 text-left [box-shadow:var(--shadow-lg)]">
        <div className="flex flex-col gap-1">
          <Heading level={2} size="sm">Sign in to Northwind</Heading>
          <Text size="sm" variant="muted">Use your work email to continue.</Text>
        </div>
        <div className="flex flex-col gap-1.5">
          <Label htmlFor="email">Work email</Label>
          <Input id="email" type="email" autoComplete="email" placeholder="you@company.com" />
        </div>
        <div className="flex flex-col gap-1.5">
          <Label htmlFor="password">Password</Label>
          <Input id="password" type="password" autoComplete="current-password" placeholder="At least 12 characters" />
        </div>
        <Button type="submit" className="w-full">Continue</Button>
      </form>
    </section>
  )
}
```

## Props

### AuroraBackgroundProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `blobCount?` | `number` | `3` | Number of gradient blobs |
| `blur?` | `number` | `80` | Blur intensity in px |
| `colors?` | `string[]` | `["var(--color-accent)", "var(--tone-i...` | Base colors for the aurora. Defaults come from theme tokens so the blobs read on light and dark scopes. |
| `duration?` | `number` | `8` | Animation duration in seconds |
| `intensity?` | `number` | `0.4` | Opacity of the aurora layer (0-1) |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- The component renders with `aria-hidden`, invisible to assistive technologies.
- Purely decorative; carries no semantic meaning.
- Reduced motion: When `prefers-reduced-motion: reduce` is active, all blob animations are paused via `motion-reduce:[animation:none]`. The static gradient blobs remain visible.

---

# Dot Pattern

> Static SVG dot grid background with configurable size, gap, and theme colors.

- id: `dot-pattern`
- type: signature
- category: Backgrounds
- tags: signature
- docs: https://glinui.com/docs/components/dot-pattern
- markdown: https://glinui.com/md/dot-pattern.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add dot-pattern
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/dot-pattern.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { DotPattern } from "@glinui/ui"
```

## Usage

```tsx
import { DotPattern, Badge, Button, Heading, Text } from "@glinui/ui"

export function Hero() {
  return (
    <section data-glin-theme="dark" className="relative isolate flex min-h-[26rem] w-full flex-col items-center justify-center gap-8 overflow-hidden rounded-xl bg-[var(--surface-0)] px-4 py-14 text-center sm:px-8">
      <DotPattern className="[mask-image:radial-gradient(520px_circle_at_center,white,transparent)]" />
      <div className="relative z-10 flex max-w-2xl flex-col items-center gap-4">
        <Badge tone="accent" variant="soft">Docs, reimagined</Badge>
        <Heading level={1} size="display">Documentation your team keeps current</Heading>
        <Text size="lg" variant="muted" className="max-w-xl">
          Write in Markdown, review in pull requests and publish to a fast static site with search and versioning built in.
        </Text>
        <div className="flex flex-wrap items-center justify-center gap-3 pt-2">
          <Button size="lg">Create a site</Button>
          <Button size="lg" variant="outline">Browse examples</Button>
        </div>
      </div>
      <div className="relative z-10 flex flex-col items-center gap-3">
        <Text size="sm" variant="muted">Works with</Text>
        <ul className="flex flex-wrap items-center justify-center gap-x-6 gap-y-2 text-[var(--color-foreground)]">
          {/* Your partner or customer logos go here */}
          <li className="text-sm font-medium">Vercel</li>
          <li className="text-sm font-medium">GitHub</li>
          <li className="text-sm font-medium">Cloudflare</li>
          <li className="text-sm font-medium">Astro</li>
        </ul>
      </div>
    </section>
  )
}
```

```tsx
import { DotPattern } from "@glinui/ui"

export function Variants() {
  return (
    <div data-glin-theme="dark" className="grid w-full gap-3 sm:grid-cols-3">
      <div className="relative isolate flex h-44 items-end overflow-hidden rounded-xl bg-[var(--surface-0)] p-3">
        <DotPattern className="[mask-image:radial-gradient(240px_circle_at_center,white,transparent)]" />
        <span className="relative z-10 rounded-full bg-black/70 px-2.5 py-1 text-xs font-medium text-white">Default</span>
      </div>
      <div className="relative isolate flex h-44 items-end overflow-hidden rounded-xl bg-[var(--surface-0)] p-3">
        <DotPattern dotSize={2.5} gap={30} dotOpacity={0.35} className="[mask-image:radial-gradient(240px_circle_at_center,white,transparent)]" />
        <span className="relative z-10 rounded-full bg-black/70 px-2.5 py-1 text-xs font-medium text-white">Large dots</span>
      </div>
      <div className="relative isolate flex h-44 items-end overflow-hidden rounded-xl bg-[var(--surface-0)] p-3">
        <DotPattern dotSize={1} gap={12} dotOpacity={0.3} className="[mask-image:radial-gradient(240px_circle_at_center,white,transparent)]" />
        <span className="relative z-10 rounded-full bg-black/70 px-2.5 py-1 text-xs font-medium text-white">Tight</span>
      </div>
    </div>
  )
}
```

```tsx
import { DotPattern, Button, Heading, Input, Label, Text } from "@glinui/ui"

export function SignIn() {
  return (
    <section data-glin-theme="dark" className="relative isolate flex min-h-[26rem] w-full items-center justify-center overflow-hidden rounded-xl bg-[var(--surface-0)] px-4 py-10">
      <DotPattern className="[mask-image:radial-gradient(520px_circle_at_center,white,transparent)]" />
      <form className="relative z-10 flex w-full max-w-sm flex-col gap-4 rounded-2xl border border-[var(--line-soft)] bg-[var(--surface-1)] p-6 text-left [box-shadow:var(--shadow-lg)]">
        <div className="flex flex-col gap-1">
          <Heading level={2} size="sm">Sign in to Northwind</Heading>
          <Text size="sm" variant="muted">Use your work email to continue.</Text>
        </div>
        <div className="flex flex-col gap-1.5">
          <Label htmlFor="email">Work email</Label>
          <Input id="email" type="email" autoComplete="email" placeholder="you@company.com" />
        </div>
        <div className="flex flex-col gap-1.5">
          <Label htmlFor="password">Password</Label>
          <Input id="password" type="password" autoComplete="current-password" placeholder="At least 12 characters" />
        </div>
        <Button type="submit" className="w-full">Continue</Button>
      </form>
    </section>
  )
}
```

## Props

### DotPatternProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `cr?` | `number` |  |  |
| `dotColor?` | `string` | `"currentColor"` |  |
| `dotOpacity?` | `number` | `0.2` |  |
| `dotSize?` | `number` | `1.5` |  |
| `gap?` | `number` | `20` |  |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- SVG is marked `aria-hidden`, invisible to screen readers.
- Purely decorative background pattern.
- Reduced motion: No animation, static SVG pattern. No reduced motion handling needed.

---

# Retro Grid

> CSS perspective grid with scrolling lines for retro-futuristic backgrounds.

- id: `retro-grid`
- type: signature
- category: Backgrounds
- tags: signature
- docs: https://glinui.com/docs/components/retro-grid
- markdown: https://glinui.com/md/retro-grid.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add retro-grid
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/retro-grid.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { RetroGrid } from "@glinui/ui"
```

## Usage

```tsx
import { RetroGrid, Badge, Button, Heading, Text } from "@glinui/ui"

export function Hero() {
  return (
    <section data-glin-theme="dark" className="relative isolate flex min-h-[26rem] w-full flex-col items-center justify-center gap-8 overflow-hidden rounded-xl bg-[var(--surface-0)] px-4 py-14 text-center sm:px-8">
      <RetroGrid />
      <div className="relative z-10 flex max-w-2xl flex-col items-center gap-4">
        <Badge tone="accent" variant="soft">Oct 21, online</Badge>
        <Heading level={1} size="display">Launch Week: five days, five releases</Heading>
        <Text size="lg" variant="muted" className="max-w-xl">
          Join the live walkthroughs, ask the engineers questions and get early access to everything we announce.
        </Text>
        <div className="flex flex-wrap items-center justify-center gap-3 pt-2">
          <Button size="lg">Save my seat</Button>
          <Button size="lg" variant="outline">See the schedule</Button>
        </div>
      </div>
      <div className="relative z-10 flex flex-col items-center gap-3">
        <Text size="sm" variant="muted">Works with</Text>
        <ul className="flex flex-wrap items-center justify-center gap-x-6 gap-y-2 text-[var(--color-foreground)]">
          {/* Your partner or customer logos go here */}
          <li className="text-sm font-medium">Vercel</li>
          <li className="text-sm font-medium">GitHub</li>
          <li className="text-sm font-medium">Cloudflare</li>
          <li className="text-sm font-medium">Astro</li>
        </ul>
      </div>
    </section>
  )
}
```

```tsx
import { RetroGrid } from "@glinui/ui"

export function Variants() {
  return (
    <div data-glin-theme="dark" className="grid w-full gap-3 sm:grid-cols-3">
      <div className="relative isolate flex h-44 items-end overflow-hidden rounded-xl bg-[var(--surface-0)] p-3">
        <RetroGrid />
        <span className="relative z-10 rounded-full bg-black/70 px-2.5 py-1 text-xs font-medium text-white">Default</span>
      </div>
      <div className="relative isolate flex h-44 items-end overflow-hidden rounded-xl bg-[var(--surface-0)] p-3">
        <RetroGrid angle={75} cellSize={40} />
        <span className="relative z-10 rounded-full bg-black/70 px-2.5 py-1 text-xs font-medium text-white">Steep angle</span>
      </div>
      <div className="relative isolate flex h-44 items-end overflow-hidden rounded-xl bg-[var(--surface-0)] p-3">
        <RetroGrid cellSize={90} lineOpacity={0.5} />
        <span className="relative z-10 rounded-full bg-black/70 px-2.5 py-1 text-xs font-medium text-white">Wide cells</span>
      </div>
    </div>
  )
}
```

```tsx
import { RetroGrid, Button, Heading, Input, Label, Text } from "@glinui/ui"

export function SignIn() {
  return (
    <section data-glin-theme="dark" className="relative isolate flex min-h-[26rem] w-full items-center justify-center overflow-hidden rounded-xl bg-[var(--surface-0)] px-4 py-10">
      <RetroGrid />
      <form className="relative z-10 flex w-full max-w-sm flex-col gap-4 rounded-2xl border border-[var(--line-soft)] bg-[var(--surface-1)] p-6 text-left [box-shadow:var(--shadow-lg)]">
        <div className="flex flex-col gap-1">
          <Heading level={2} size="sm">Sign in to Northwind</Heading>
          <Text size="sm" variant="muted">Use your work email to continue.</Text>
        </div>
        <div className="flex flex-col gap-1.5">
          <Label htmlFor="email">Work email</Label>
          <Input id="email" type="email" autoComplete="email" placeholder="you@company.com" />
        </div>
        <div className="flex flex-col gap-1.5">
          <Label htmlFor="password">Password</Label>
          <Input id="password" type="password" autoComplete="current-password" placeholder="At least 12 characters" />
        </div>
        <Button type="submit" className="w-full">Continue</Button>
      </form>
    </section>
  )
}
```

## Props

### RetroGridProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `angle?` | `number` | `65` | Perspective angle in degrees |
| `cellSize?` | `number` | `60` | Grid cell size in px |
| `lineColor?` | `string` |  | Grid line color |
| `lineOpacity?` | `number` | `0.3` | Grid line opacity (0-1) |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- The grid element is marked `aria-hidden="true"`, invisible to assistive technologies.
- Purely decorative; carries no semantic meaning.
- Reduced motion: The perspective scroll animation is paused via `motion-reduce:animate-none` and `motion-reduce:[animation-play-state:paused]`. The static grid remains visible so the layout is unaffected.

---

# Grid Pattern

> SVG grid, stripes and interactive cell patterns with edge fades.

- id: `grid-pattern`
- type: primitive
- category: Backgrounds
- tags: primitive, adapted
- docs: https://glinui.com/docs/components/radix/grid-pattern
- markdown: https://glinui.com/md/grid-pattern.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add grid-pattern
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/grid-pattern.json
```

Package:

```bash
npm install @glinui/ui @glinui/motion @glinui/tokens
```

## Import

```tsx
import { GridPattern, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider } from "@glinui/ui"
```

## Usage

Adapted from Grid Pattern, Interactive Grid Pattern and Striped Pattern by Magic UI (MIT). Glin UI merges the three into one component with a variant prop, creates collision-free SVG pattern ids with useId, draws strokes with currentColor tied to the line token, and runs the interactive hover with CSS only.

Use the fade prop (or your own mask) so the pattern dissolves toward the edges. Interactive cells need pointer events: content layered above the pattern will intercept them, and the cell count is capped at 1600.

Highlighted squares pulse only at motion level full.

Headline, subcopy, two buttons and a logo row sit above the effect. The section opts into the dark token scope so text keeps AA contrast. The logo row uses docs-only BrandIcon marks; swap in your own logos.

```tsx
import { GridPattern, Badge, Button, Heading, Text } from "@glinui/ui"

export function Hero() {
  return (
    <section data-glin-theme="dark" className="relative isolate flex min-h-[26rem] w-full flex-col items-center justify-center gap-8 overflow-hidden rounded-xl bg-[var(--surface-0)] px-4 py-14 text-center sm:px-8">
      <GridPattern fade="radial" squares={[[4, 4], [5, 1], [8, 2], [10, 5], [2, 2]]} />
      <div className="relative z-10 flex max-w-2xl flex-col items-center gap-4">
        <Badge tone="accent" variant="soft">Open source</Badge>
        <Heading level={1} size="display">A typed API client in every language</Heading>
        <Text size="lg" variant="muted" className="max-w-xl">
          Generate SDKs from your OpenAPI spec on every merge and publish them to npm, PyPI and Maven without leaving CI.
        </Text>
        <div className="flex flex-wrap items-center justify-center gap-3 pt-2">
          <Button size="lg">Generate an SDK</Button>
          <Button size="lg" variant="outline">View on GitHub</Button>
        </div>
      </div>
      <div className="relative z-10 flex flex-col items-center gap-3">
        <Text size="sm" variant="muted">Works with</Text>
        <ul className="flex flex-wrap items-center justify-center gap-x-6 gap-y-2 text-[var(--color-foreground)]">
          {/* Your partner or customer logos go here */}
          <li className="text-sm font-medium">Vercel</li>
          <li className="text-sm font-medium">GitHub</li>
          <li className="text-sm font-medium">Cloudflare</li>
          <li className="text-sm font-medium">Astro</li>
        </ul>
      </div>
    </section>
  )
}
```

### Variants

Plain grid, dashed grid and the stripes variant.

```tsx
import { GridPattern } from "@glinui/ui"

export function Variants() {
  return (
    <div data-glin-theme="dark" className="grid w-full gap-3 sm:grid-cols-3">
      <div className="relative isolate flex h-44 items-end overflow-hidden rounded-xl bg-[var(--surface-0)] p-3">
        <GridPattern fade="radial" />
        <span className="relative z-10 rounded-full bg-black/70 px-2.5 py-1 text-xs font-medium text-white">Grid</span>
      </div>
      <div className="relative isolate flex h-44 items-end overflow-hidden rounded-xl bg-[var(--surface-0)] p-3">
        <GridPattern fade="radial" strokeDasharray="4 2" width={32} height={32} />
        <span className="relative z-10 rounded-full bg-black/70 px-2.5 py-1 text-xs font-medium text-white">Dashed</span>
      </div>
      <div className="relative isolate flex h-44 items-end overflow-hidden rounded-xl bg-[var(--surface-0)] p-3">
        <GridPattern variant="stripes" width={12} height={12} fade="bottom" />
        <span className="relative z-10 rounded-full bg-black/70 px-2.5 py-1 text-xs font-medium text-white">Stripes</span>
      </div>
    </div>
  )
}
```

### Behind a dashboard header

A faded grid gives dashboard headers structure without competing with the data.

```tsx
import { GridPattern, Button, Heading, Text } from "@glinui/ui"

const stats = [
  ["Requests", "2.41M", "+8.2%"],
  ["p95 latency", "184 ms", "-12 ms"],
  ["Error rate", "0.03%", "-0.01%"]
]

export function UsageHeader() {
  return (
    <section data-glin-theme="dark" className="relative isolate flex min-h-[22rem] w-full flex-col justify-end gap-6 overflow-hidden rounded-xl bg-[var(--surface-0)] p-6 sm:p-8">
      <GridPattern fade="radial" squares={[[4, 4], [5, 1], [8, 2], [10, 5], [2, 2]]} />
      <div className="relative z-10 flex flex-wrap items-end justify-between gap-4">
        <div className="flex flex-col gap-1">
          <Text variant="eyebrow">Production, last 24 hours</Text>
          <Heading level={2} size="md">API overview</Heading>
        </div>
        <div className="flex gap-2">
          <Button size="sm" variant="outline">Export CSV</Button>
          <Button size="sm">Create alert</Button>
        </div>
      </div>
      <dl className="relative z-10 grid gap-3 sm:grid-cols-3">
        {stats.map(([label, value, delta]) => (
          <div key={label} className="rounded-xl border border-[var(--line-soft)] bg-[var(--surface-1)] p-4">
            <dt className="text-xs text-[var(--color-muted)]">{label}</dt>
            <dd className="mt-1 text-2xl font-semibold tabular-nums text-[var(--color-foreground)]">{value}</dd>
            <dd className="text-xs text-[var(--tone-success-text)]">{delta} vs yesterday</dd>
          </div>
        ))}
      </dl>
    </section>
  )
}
```

## Props

### GridPatternProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `fade?` | `"none" \| "radial" \| "top" \| "bottom"` | `"none"` | Variant option from gridPatternVariants. |
| `height?` | `number` | `40` | Cell height in px. |
| `interactive?` | `boolean` | `false` | Cells light up on hover (CSS only). Content above the pattern will block pointer events. |
| `squareColor?` | `string` | `"var(--color-accent)"` | Fill of highlighted and hovered cells. Defaults to the accent token. |
| `squares?` | `GridPatternSquare[]` |  | Highlighted cells as [column, row] pairs. |
| `strokeDasharray?` | `string` | `"0"` |  |
| `variant?` | `"grid" \| "stripes"` | `"grid"` | Variant option from gridPatternVariants. |
| `width?` | `number` | `40` | Cell width in px. |
| `x?` | `number` | `-1` |  |
| `y?` | `number` | `-1` |  |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `grid`, `stripes`.

## Accessibility

- Decorative: aria-hidden, not focusable, pointer-events none (interactive cells opt back in).
- Hover highlighting is a visual flourish only and has no keyboard equivalent by design.
- Keep line contrast low behind text.

ARIA:

- `aria-hidden="true"` and `focusable="false"` on the svg

- Reduced motion: Highlighted squares pulse at motion level full. With reduced motion or level none or subtle the squares are static, and hover cell transitions are removed.

## Provenance

Adapted from Magic UI (MIT, Copyright (c) Magic UI). Upstream: https://magicui.design/docs/components/grid-pattern. Restyled to Glin tokens with accessibility and reduced motion review. Keep the attribution when you copy this component.

---

# Flickering Grid

> Canvas grid of squares that flicker, with token colors and a static fallback.

- id: `flickering-grid`
- type: primitive
- category: Backgrounds
- tags: primitive, adapted
- docs: https://glinui.com/docs/components/radix/flickering-grid
- markdown: https://glinui.com/md/flickering-grid.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add flickering-grid
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/flickering-grid.json
```

Package:

```bash
npm install @glinui/ui @glinui/motion @glinui/tokens
```

## Import

```tsx
import { FlickeringGrid, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider } from "@glinui/ui"
```

## Usage

Adapted from Flickering Grid by Magic UI (MIT). Glin UI resolves token and modern CSS colors (var(), oklch(), color-mix()) at runtime and re-resolves them when the theme changes, draws with a devicePixelRatio transform, caps the frame rate (30 fps by default), pauses the loop offscreen and in background tabs, uses a seeded starting pattern, and draws one static frame under reduced motion.

The grid fills its parent (size-full), so give the parent a size. Keep maxOpacity at 0.3 or lower behind text. The loop costs battery, so avoid stacking several grids on one page.

Headline, subcopy, two buttons and a logo row sit above the effect. The section opts into the dark token scope so text keeps AA contrast. The logo row uses docs-only BrandIcon marks; swap in your own logos.

```tsx
import { FlickeringGrid, Badge, Button, Heading, Text } from "@glinui/ui"

export function Hero() {
  return (
    <section data-glin-theme="dark" className="relative isolate flex min-h-[26rem] w-full flex-col items-center justify-center gap-8 overflow-hidden rounded-xl bg-[var(--surface-0)] px-4 py-14 text-center sm:px-8">
      <FlickeringGrid squareSize={4} gridGap={6} maxOpacity={0.35} className="absolute inset-0" />
      <div className="relative z-10 flex max-w-2xl flex-col items-center gap-4">
        <Badge tone="accent" variant="soft">Status</Badge>
        <Heading level={1} size="display">Know about the outage before your users do</Heading>
        <Text size="lg" variant="muted" className="max-w-xl">
          Probe from 14 regions every 30 seconds, route alerts to the right on-call and publish incidents to a status page.
        </Text>
        <div className="flex flex-wrap items-center justify-center gap-3 pt-2">
          <Button size="lg">Start monitoring</Button>
          <Button size="lg" variant="outline">View pricing</Button>
        </div>
      </div>
      <div className="relative z-10 flex flex-col items-center gap-3">
        <Text size="sm" variant="muted">Works with</Text>
        <ul className="flex flex-wrap items-center justify-center gap-x-6 gap-y-2 text-[var(--color-foreground)]">
          {/* Your partner or customer logos go here */}
          <li className="text-sm font-medium">Vercel</li>
          <li className="text-sm font-medium">GitHub</li>
          <li className="text-sm font-medium">Cloudflare</li>
          <li className="text-sm font-medium">Astro</li>
        </ul>
      </div>
    </section>
  )
}
```

### Variants

Square and round cells, and a busier field with a higher flicker chance.

```tsx
import { FlickeringGrid } from "@glinui/ui"

export function Variants() {
  return (
    <div data-glin-theme="dark" className="grid w-full gap-3 sm:grid-cols-3">
      <div className="relative isolate flex h-44 items-end overflow-hidden rounded-xl bg-[var(--surface-0)] p-3">
        <FlickeringGrid squareSize={4} gridGap={6} maxOpacity={0.4} className="absolute inset-0" />
        <span className="relative z-10 rounded-full bg-black/70 px-2.5 py-1 text-xs font-medium text-white">Square</span>
      </div>
      <div className="relative isolate flex h-44 items-end overflow-hidden rounded-xl bg-[var(--surface-0)] p-3">
        <FlickeringGrid variant="round" squareSize={4} gridGap={8} maxOpacity={0.4} className="absolute inset-0" />
        <span className="relative z-10 rounded-full bg-black/70 px-2.5 py-1 text-xs font-medium text-white">Round</span>
      </div>
      <div className="relative isolate flex h-44 items-end overflow-hidden rounded-xl bg-[var(--surface-0)] p-3">
        <FlickeringGrid squareSize={3} gridGap={5} flickerChance={0.6} maxOpacity={0.4} className="absolute inset-0" />
        <span className="relative z-10 rounded-full bg-black/70 px-2.5 py-1 text-xs font-medium text-white">Busy</span>
      </div>
    </div>
  )
}
```

### Behind a dashboard header

A quiet flicker behind live metrics suggests activity without distracting from numbers.

```tsx
import { FlickeringGrid, Button, Heading, Text } from "@glinui/ui"

const stats = [
  ["Requests", "2.41M", "+8.2%"],
  ["p95 latency", "184 ms", "-12 ms"],
  ["Error rate", "0.03%", "-0.01%"]
]

export function UsageHeader() {
  return (
    <section data-glin-theme="dark" className="relative isolate flex min-h-[22rem] w-full flex-col justify-end gap-6 overflow-hidden rounded-xl bg-[var(--surface-0)] p-6 sm:p-8">
      <FlickeringGrid squareSize={4} gridGap={6} maxOpacity={0.35} className="absolute inset-0" />
      <div className="relative z-10 flex flex-wrap items-end justify-between gap-4">
        <div className="flex flex-col gap-1">
          <Text variant="eyebrow">Production, last 24 hours</Text>
          <Heading level={2} size="md">API overview</Heading>
        </div>
        <div className="flex gap-2">
          <Button size="sm" variant="outline">Export CSV</Button>
          <Button size="sm">Create alert</Button>
        </div>
      </div>
      <dl className="relative z-10 grid gap-3 sm:grid-cols-3">
        {stats.map(([label, value, delta]) => (
          <div key={label} className="rounded-xl border border-[var(--line-soft)] bg-[var(--surface-1)] p-4">
            <dt className="text-xs text-[var(--color-muted)]">{label}</dt>
            <dd className="mt-1 text-2xl font-semibold tabular-nums text-[var(--color-foreground)]">{value}</dd>
            <dd className="text-xs text-[var(--tone-success-text)]">{delta} vs yesterday</dd>
          </div>
        ))}
      </dl>
    </section>
  )
}
```

## Props

### FlickeringGridProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `color?` | `string` | `"var(--color-foreground)"` | Any CSS color, including var(), oklch() and color-mix(). Defaults to the foreground token. |
| `flickerChance?` | `number` | `0.3` | Chance per second that a square re-rolls its opacity. |
| `gridGap?` | `number` | `6` | Gap between squares in px. |
| `maxFps?` | `number` | `30` | Frame cap for the flicker loop. |
| `maxOpacity?` | `number` | `0.3` | Highest opacity a square can reach. Keep at or below 0.3 behind text. |
| `seed?` | `number` | `7` | Seed for the deterministic starting pattern. |
| `squareSize?` | `number` | `4` | Square edge in px. |
| `variant?` | `"square" \| "round"` | `"square"` |  |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `square`, `round`.

## Accessibility

- Decorative canvas: aria-hidden, pointer-events none.
- Flicker is low contrast and slow. Keep maxOpacity at 0.3 or lower; it never flashes more than three times per second per cell on average at default settings.
- Content on top should still meet AA contrast.

ARIA:

- `aria-hidden="true"` on the wrapper

- Reduced motion: At motion level full squares flicker through requestAnimationFrame. With prefers-reduced-motion or level none or subtle the grid draws a single static frame. The loop pauses offscreen and when the tab is hidden.

## Provenance

Adapted from Magic UI (MIT, Copyright (c) Magic UI). Upstream: https://magicui.design/docs/components/flickering-grid. Restyled to Glin tokens with accessibility and reduced motion review. Keep the attribution when you copy this component.

---

# Spotlight

> Full-page spotlight overlay for onboarding and feature highlighting.

- id: `spotlight`
- type: signature
- category: Backgrounds
- tags: signature
- docs: https://glinui.com/docs/components/spotlight
- markdown: https://glinui.com/md/spotlight.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add spotlight
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/spotlight.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Spotlight } from "@glinui/ui"
```

## Usage

```tsx
"use client"
import { Spotlight } from "@glinui/ui"
import { useState } from "react"

export function SpotlightDemo() {
  const [active, setActive] = useState(false)
  return (
    <div className="relative flex h-72 w-full items-center justify-center overflow-hidden rounded-xl">
      <button
        type="button"
        className="rounded-lg bg-[var(--color-accent)] px-4 py-2 text-sm font-medium text-[var(--color-accent-foreground)]"
        onClick={() => setActive(true)}
      >
        Show Spotlight
      </button>
      <Spotlight
        active={active}
        className="absolute z-10"
        x="50%"
        y="50%"
        size={120}
        onDismiss={() => setActive(false)}
      />
    </div>
  )
}
```

```tsx
"use client"
import { Spotlight } from "@glinui/ui"

export function SpotlightPulseDemo() {
  return (
    <Spotlight
      active
      x="50%"
      y="50%"
      size={100}
      pulse
      onDismiss={() => {}}
    />
  )
}
```

## Props

### SpotlightProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `active?` | `boolean` | `true` | Whether the spotlight is active |
| `onDismiss?` | `() => void` |  | Click overlay to dismiss |
| `overlayColor?` | `string` | `"rgba(0, 0, 0, 0.7)"` | Overlay color |
| `pulse?` | `boolean` | `false` | Pulsing animation |
| `size?` | `number` | `150` | Spotlight radius in px |
| `x?` | `number \| string` | `"50%"` | X position of spotlight center (px or %) |
| `y?` | `number \| string` | `"50%"` | Y position of spotlight center (px or %) |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- When `onDismiss` is provided, the overlay becomes a focusable button with `aria-label="Dismiss spotlight"`.
- Supports keyboard dismissal via Enter and Space keys.
- Without `onDismiss`, the overlay is a passive visual element.
- Reduced motion: The pulse ring animation is paused via `motion-reduce:[animation:none]`.

---

# Blur Spotlight

> Cursor-following ambient glow effect for background layers.

- id: `blur-spotlight`
- type: signature
- category: Backgrounds
- tags: signature
- docs: https://glinui.com/docs/components/blur-spotlight
- markdown: https://glinui.com/md/blur-spotlight.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add blur-spotlight
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/blur-spotlight.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { BlurSpotlight } from "@glinui/ui"
```

## Usage

```tsx
"use client"
import { BlurSpotlight } from "@glinui/ui"

export function BlurSpotlightDemo() {
  return (
    <div className="relative flex h-72 w-full items-center justify-center overflow-hidden rounded-xl border border-[var(--color-border)] bg-[var(--surface-1)]">
      <BlurSpotlight />
      <span className="relative z-10 text-3xl font-bold text-[var(--color-foreground)]">Hover Me</span>
    </div>
  )
}
```

```tsx
"use client"
import { BlurSpotlight } from "@glinui/ui"

export function BlurSpotlightCustomDemo() {
  return (
    <div className="relative flex h-64 w-full items-center justify-center overflow-hidden rounded-xl border border-[var(--color-border)] bg-[var(--surface-1)]">
      <BlurSpotlight color="#ec4899" size={400} intensity={0.6} />
      <span className="relative z-10 text-2xl font-bold text-[var(--color-foreground)]">Pink Glow</span>
    </div>
  )
}
```

```tsx
"use client"
import { BlurSpotlight } from "@glinui/ui"

export function BlurSpotlightSubtleDemo() {
  return (
    <div className="relative flex h-64 w-full items-center justify-center overflow-hidden rounded-xl border border-[var(--color-border)] bg-[var(--surface-1)]">
      <BlurSpotlight size={200} blur={120} intensity={0.3} />
      <span className="relative z-10 text-2xl font-bold text-[var(--color-foreground)]">Subtle</span>
    </div>
  )
}
```

## Props

### BlurSpotlightProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `blur?` | `number` | `80` | Blur amount in px |
| `color?` | `string` | `"var(--color-accent)"` | Spotlight color |
| `intensity?` | `number` | `0.5` | Intensity/opacity (0-1) |
| `size?` | `number` | `300` | Spotlight radius in px |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- The component renders with `aria-hidden`, invisible to assistive technologies.
- Purely decorative; carries no semantic meaning.
- `pointer-events-none` ensures content beneath remains interactive.
- Reduced motion: The entire spotlight layer is hidden via `motion-reduce:hidden` when reduced motion is preferred.

---

# Light Rays

> Soft swaying rays of light for hero and section backgrounds.

- id: `light-rays`
- type: primitive
- category: Backgrounds
- tags: primitive, adapted
- docs: https://glinui.com/docs/components/radix/light-rays
- markdown: https://glinui.com/md/light-rays.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add light-rays
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/light-rays.json
```

Package:

```bash
npm install @glinui/ui @glinui/motion @glinui/tokens
```

## Import

```tsx
import { LightRays, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider } from "@glinui/ui"
```

## Usage

Adapted from Light Rays by Magic UI (MIT). Glin UI replaces the motion library with the Web Animations API, builds a deterministic seeded ray layout (no Math.random during render, so no hydration mismatch), reads the accent token, mirrors in RTL, and pauses when offscreen or when the tab is hidden.

Place the component as the first child of a relative parent and keep it behind content (use -z-10 or DOM order). Recommended intensity is 0.5 or lower behind body text so contrast stays at WCAG AA.

Large blur radii are expensive to paint. Count is capped at 24 and only the rays carry will-change.

Headline, subcopy, two buttons and a logo row sit above the effect. The section opts into the dark token scope so text keeps AA contrast. The logo row uses docs-only BrandIcon marks; swap in your own logos.

```tsx
import { LightRays, Badge, Button, Heading, Text } from "@glinui/ui"

export function Hero() {
  return (
    <section data-glin-theme="dark" className="relative isolate flex min-h-[26rem] w-full flex-col items-center justify-center gap-8 overflow-hidden rounded-xl bg-[var(--surface-0)] px-4 py-14 text-center sm:px-8">
      <LightRays intensity={0.4} />
      <div className="relative z-10 flex max-w-2xl flex-col items-center gap-4">
        <Badge tone="accent" variant="soft">SOC 2 Type II</Badge>
        <Heading level={1} size="display">See every login before it becomes an incident</Heading>
        <Text size="lg" variant="muted" className="max-w-xl">
          Risk scoring on each sign in, device trust checks and one click session revocation from a single audit trail.
        </Text>
        <div className="flex flex-wrap items-center justify-center gap-3 pt-2">
          <Button size="lg">Book a review</Button>
          <Button size="lg" variant="outline">Security overview</Button>
        </div>
      </div>
      <div className="relative z-10 flex flex-col items-center gap-3">
        <Text size="sm" variant="muted">Works with</Text>
        <ul className="flex flex-wrap items-center justify-center gap-x-6 gap-y-2 text-[var(--color-foreground)]">
          {/* Your partner or customer logos go here */}
          <li className="text-sm font-medium">Vercel</li>
          <li className="text-sm font-medium">GitHub</li>
          <li className="text-sm font-medium">Cloudflare</li>
          <li className="text-sm font-medium">Astro</li>
        </ul>
      </div>
    </section>
  )
}
```

### Variants

Soft rays, crisp rays and another seed for a different layout.

```tsx
import { LightRays } from "@glinui/ui"

export function Variants() {
  return (
    <div data-glin-theme="dark" className="grid w-full gap-3 sm:grid-cols-3">
      <div className="relative isolate flex h-44 items-end overflow-hidden rounded-xl bg-[var(--surface-0)] p-3">
        <LightRays intensity={0.45} />
        <span className="relative z-10 rounded-full bg-black/70 px-2.5 py-1 text-xs font-medium text-white">Soft</span>
      </div>
      <div className="relative isolate flex h-44 items-end overflow-hidden rounded-xl bg-[var(--surface-0)] p-3">
        <LightRays variant="crisp" count={5} intensity={0.45} />
        <span className="relative z-10 rounded-full bg-black/70 px-2.5 py-1 text-xs font-medium text-white">Crisp</span>
      </div>
      <div className="relative isolate flex h-44 items-end overflow-hidden rounded-xl bg-[var(--surface-0)] p-3">
        <LightRays seed={4} count={9} blur={40} intensity={0.45} />
        <span className="relative z-10 rounded-full bg-black/70 px-2.5 py-1 text-xs font-medium text-white">Seed 4</span>
      </div>
    </div>
  )
}
```

### Behind a sign in card

Rays at intensity 0.45 or lower keep body text above AA contrast.

```tsx
import { LightRays, Button, Heading, Input, Label, Text } from "@glinui/ui"

export function SignIn() {
  return (
    <section data-glin-theme="dark" className="relative isolate flex min-h-[26rem] w-full items-center justify-center overflow-hidden rounded-xl bg-[var(--surface-0)] px-4 py-10">
      <LightRays intensity={0.4} />
      <form className="relative z-10 flex w-full max-w-sm flex-col gap-4 rounded-2xl border border-[var(--line-soft)] bg-[var(--surface-1)] p-6 text-left [box-shadow:var(--shadow-lg)]">
        <div className="flex flex-col gap-1">
          <Heading level={2} size="sm">Sign in to Northwind</Heading>
          <Text size="sm" variant="muted">Use your work email to continue.</Text>
        </div>
        <div className="flex flex-col gap-1.5">
          <Label htmlFor="email">Work email</Label>
          <Input id="email" type="email" autoComplete="email" placeholder="you@company.com" />
        </div>
        <div className="flex flex-col gap-1.5">
          <Label htmlFor="password">Password</Label>
          <Input id="password" type="password" autoComplete="current-password" placeholder="At least 12 characters" />
        </div>
        <Button type="submit" className="w-full">Continue</Button>
      </form>
    </section>
  )
}
```

## Props

### LightRaysProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `blur?` | `number` |  | Blur radius in px. Defaults to 24 (soft) or 6 (crisp). |
| `color?` | `string` | `"var(--color-accent)"` | Any CSS color. Defaults to the accent token. |
| `count?` | `number` | `7` | Number of rays, capped at 24. |
| `intensity?` | `number` | `0.35` | Overall strength from 0 to 1. Keep at or below 0.5 behind text. |
| `length?` | `string` | `"120%"` | CSS length of each ray, for example "70%" or "28rem". |
| `seed?` | `number` | `1` | Seed for the deterministic ray layout. |
| `speed?` | `number` | `14` | Seconds for one sway cycle. |
| `variant?` | `"soft" \| "crisp"` | `"soft"` | Variant option from lightRaysVariants. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `soft`, `crisp`.

## Accessibility

- Purely decorative: aria-hidden and pointer-events none, never focusable.
- Keep intensity at 0.5 or lower behind text; verify AA contrast on your own background.
- No information is carried by the rays.

ARIA:

- `aria-hidden="true"` on the root

- Reduced motion: At motion level full the rays sway with WAAPI. With prefers-reduced-motion or data-glin-motion none or subtle, the rays render as a static frame with no animation. Animations also pause offscreen and in background tabs.

## Provenance

Adapted from Magic UI (MIT, Copyright (c) Magic UI). Upstream: https://magicui.design/docs/components/light-rays. Restyled to Glin tokens with accessibility and reduced motion review. Keep the attribution when you copy this component.

---

# Particle Field

> Ambient floating particle system with CSS-only staggered animations.

- id: `particle-field`
- type: signature
- category: Backgrounds
- tags: signature
- docs: https://glinui.com/docs/components/particle-field
- markdown: https://glinui.com/md/particle-field.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add particle-field
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/particle-field.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { ParticleField } from "@glinui/ui"
```

## Usage

```tsx
import { ParticleField, Badge, Button, Heading, Text } from "@glinui/ui"

export function Hero() {
  return (
    <section data-glin-theme="dark" className="relative isolate flex min-h-[26rem] w-full flex-col items-center justify-center gap-8 overflow-hidden rounded-xl bg-[var(--surface-0)] px-4 py-14 text-center sm:px-8">
      <ParticleField count={40} />
      <div className="relative z-10 flex max-w-2xl flex-col items-center gap-4">
        <Badge tone="accent" variant="soft">Realtime</Badge>
        <Heading level={1} size="display">Presence for every page, in one hook</Heading>
        <Text size="lg" variant="muted" className="max-w-xl">
          Show who is viewing, typing and pointing without running your own socket servers or paying per connection.
        </Text>
        <div className="flex flex-wrap items-center justify-center gap-3 pt-2">
          <Button size="lg">Add presence</Button>
          <Button size="lg" variant="outline">Try the demo</Button>
        </div>
      </div>
      <div className="relative z-10 flex flex-col items-center gap-3">
        <Text size="sm" variant="muted">Works with</Text>
        <ul className="flex flex-wrap items-center justify-center gap-x-6 gap-y-2 text-[var(--color-foreground)]">
          {/* Your partner or customer logos go here */}
          <li className="text-sm font-medium">Vercel</li>
          <li className="text-sm font-medium">GitHub</li>
          <li className="text-sm font-medium">Cloudflare</li>
          <li className="text-sm font-medium">Astro</li>
        </ul>
      </div>
    </section>
  )
}
```

```tsx
import { ParticleField } from "@glinui/ui"

export function Variants() {
  return (
    <div data-glin-theme="dark" className="grid w-full gap-3 sm:grid-cols-3">
      <div className="relative isolate flex h-44 items-end overflow-hidden rounded-xl bg-[var(--surface-0)] p-3">
        <ParticleField count={30} />
        <span className="relative z-10 rounded-full bg-black/70 px-2.5 py-1 text-xs font-medium text-white">Default</span>
      </div>
      <div className="relative isolate flex h-44 items-end overflow-hidden rounded-xl bg-[var(--surface-0)] p-3">
        <ParticleField count={30} shape="square" maxSize={5} />
        <span className="relative z-10 rounded-full bg-black/70 px-2.5 py-1 text-xs font-medium text-white">Squares</span>
      </div>
      <div className="relative isolate flex h-44 items-end overflow-hidden rounded-xl bg-[var(--surface-0)] p-3">
        <ParticleField count={24} distance={140} duration={10} />
        <span className="relative z-10 rounded-full bg-black/70 px-2.5 py-1 text-xs font-medium text-white">Long drift</span>
      </div>
    </div>
  )
}
```

```tsx
import { ParticleField, Button, Heading, Text } from "@glinui/ui"

const stats = [
  ["Requests", "2.41M", "+8.2%"],
  ["p95 latency", "184 ms", "-12 ms"],
  ["Error rate", "0.03%", "-0.01%"]
]

export function UsageHeader() {
  return (
    <section data-glin-theme="dark" className="relative isolate flex min-h-[22rem] w-full flex-col justify-end gap-6 overflow-hidden rounded-xl bg-[var(--surface-0)] p-6 sm:p-8">
      <ParticleField count={40} />
      <div className="relative z-10 flex flex-wrap items-end justify-between gap-4">
        <div className="flex flex-col gap-1">
          <Text variant="eyebrow">Production, last 24 hours</Text>
          <Heading level={2} size="md">API overview</Heading>
        </div>
        <div className="flex gap-2">
          <Button size="sm" variant="outline">Export CSV</Button>
          <Button size="sm">Create alert</Button>
        </div>
      </div>
      <dl className="relative z-10 grid gap-3 sm:grid-cols-3">
        {stats.map(([label, value, delta]) => (
          <div key={label} className="rounded-xl border border-[var(--line-soft)] bg-[var(--surface-1)] p-4">
            <dt className="text-xs text-[var(--color-muted)]">{label}</dt>
            <dd className="mt-1 text-2xl font-semibold tabular-nums text-[var(--color-foreground)]">{value}</dd>
            <dd className="text-xs text-[var(--tone-success-text)]">{delta} vs yesterday</dd>
          </div>
        ))}
      </dl>
    </section>
  )
}
```

## Props

### ParticleFieldProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `color?` | `string` |  | Particle color |
| `count?` | `number` | `30` | Number of particles |
| `distance?` | `number` | `200` | Float distance in px |
| `duration?` | `number` | `5` | Float duration in seconds |
| `maxSize?` | `number` | `5` | Max particle size in px |
| `minSize?` | `number` | `2` | Min particle size in px |
| `shape?` | `"circle" \| "square"` | `"circle"` | Particle shape |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- The component renders with `aria-hidden`, invisible to assistive technologies.
- Purely decorative; carries no semantic meaning.
- Reduced motion: All particle animations are paused via `motion-reduce:[animation:none]`. The static particles remain visible.

---

# Meteor Shower

> Falling diagonal streaks with staggered delays for hero backgrounds.

- id: `meteor-shower`
- type: signature
- category: Backgrounds
- tags: signature
- docs: https://glinui.com/docs/components/meteor-shower
- markdown: https://glinui.com/md/meteor-shower.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add meteor-shower
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/meteor-shower.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { MeteorShower } from "@glinui/ui"
```

## Usage

```tsx
import { MeteorShower, Badge, Button, Heading, Text } from "@glinui/ui"

export function Hero() {
  return (
    <section data-glin-theme="dark" className="relative isolate flex min-h-[26rem] w-full flex-col items-center justify-center gap-8 overflow-hidden rounded-xl bg-[var(--surface-0)] px-4 py-14 text-center sm:px-8">
      <MeteorShower count={14} />
      <div className="relative z-10 flex max-w-2xl flex-col items-center gap-4">
        <Badge tone="accent" variant="soft">Changelog</Badge>
        <Heading level={1} size="display">Everything we shipped this quarter</Heading>
        <Text size="lg" variant="muted" className="max-w-xl">
          Forty two improvements across builds, caching and observability, with migration notes where behavior changed.
        </Text>
        <div className="flex flex-wrap items-center justify-center gap-3 pt-2">
          <Button size="lg">Read the changelog</Button>
          <Button size="lg" variant="outline">Subscribe</Button>
        </div>
      </div>
      <div className="relative z-10 flex flex-col items-center gap-3">
        <Text size="sm" variant="muted">Works with</Text>
        <ul className="flex flex-wrap items-center justify-center gap-x-6 gap-y-2 text-[var(--color-foreground)]">
          {/* Your partner or customer logos go here */}
          <li className="text-sm font-medium">Vercel</li>
          <li className="text-sm font-medium">GitHub</li>
          <li className="text-sm font-medium">Cloudflare</li>
          <li className="text-sm font-medium">Astro</li>
        </ul>
      </div>
    </section>
  )
}
```

```tsx
import { MeteorShower } from "@glinui/ui"

export function Variants() {
  return (
    <div data-glin-theme="dark" className="grid w-full gap-3 sm:grid-cols-3">
      <div className="relative isolate flex h-44 items-end overflow-hidden rounded-xl bg-[var(--surface-0)] p-3">
        <MeteorShower count={10} />
        <span className="relative z-10 rounded-full bg-black/70 px-2.5 py-1 text-xs font-medium text-white">Default</span>
      </div>
      <div className="relative isolate flex h-44 items-end overflow-hidden rounded-xl bg-[var(--surface-0)] p-3">
        <MeteorShower count={10} angle={235} />
        <span className="relative z-10 rounded-full bg-black/70 px-2.5 py-1 text-xs font-medium text-white">Steep</span>
      </div>
      <div className="relative isolate flex h-44 items-end overflow-hidden rounded-xl bg-[var(--surface-0)] p-3">
        <MeteorShower count={24} minDuration={2} maxDuration={5} />
        <span className="relative z-10 rounded-full bg-black/70 px-2.5 py-1 text-xs font-medium text-white">Heavy</span>
      </div>
    </div>
  )
}
```

```tsx
import { MeteorShower, Button, Heading, Input, Label, Text } from "@glinui/ui"

export function SignIn() {
  return (
    <section data-glin-theme="dark" className="relative isolate flex min-h-[26rem] w-full items-center justify-center overflow-hidden rounded-xl bg-[var(--surface-0)] px-4 py-10">
      <MeteorShower count={14} />
      <form className="relative z-10 flex w-full max-w-sm flex-col gap-4 rounded-2xl border border-[var(--line-soft)] bg-[var(--surface-1)] p-6 text-left [box-shadow:var(--shadow-lg)]">
        <div className="flex flex-col gap-1">
          <Heading level={2} size="sm">Sign in to Northwind</Heading>
          <Text size="sm" variant="muted">Use your work email to continue.</Text>
        </div>
        <div className="flex flex-col gap-1.5">
          <Label htmlFor="email">Work email</Label>
          <Input id="email" type="email" autoComplete="email" placeholder="you@company.com" />
        </div>
        <div className="flex flex-col gap-1.5">
          <Label htmlFor="password">Password</Label>
          <Input id="password" type="password" autoComplete="current-password" placeholder="At least 12 characters" />
        </div>
        <Button type="submit" className="w-full">Continue</Button>
      </form>
    </section>
  )
}
```

## Props

### MeteorShowerProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `angle?` | `number` | `215` |  |
| `count?` | `number` | `12` |  |
| `maxDelay?` | `number` | `4` |  |
| `maxDuration?` | `number` | `5` |  |
| `minDelay?` | `number` | `0` |  |
| `minDuration?` | `number` | `2` |  |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Decorative (`aria-hidden`), invisible to screen readers.
- No interactive elements.
- Reduced motion: Component returns `null` when `prefers-reduced-motion` is active.

---

# Light Leak

> Simulated lens flare and light leak overlay with drifting animation.

- id: `light-leak`
- type: signature
- category: Backgrounds
- tags: signature
- docs: https://glinui.com/docs/components/light-leak
- markdown: https://glinui.com/md/light-leak.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add light-leak
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/light-leak.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { LightLeak } from "@glinui/ui"
```

## Usage

```tsx
import { LightLeak, Badge, Button, Heading, Text } from "@glinui/ui"

export function Hero() {
  return (
    <section data-glin-theme="dark" className="relative isolate flex min-h-[26rem] w-full flex-col items-center justify-center gap-8 overflow-hidden rounded-xl bg-[var(--surface-0)] px-4 py-14 text-center sm:px-8">
      <LightLeak intensity={0.5} />
      <div className="relative z-10 flex max-w-2xl flex-col items-center gap-4">
        <Badge tone="accent" variant="soft">Film presets</Badge>
        <Heading level={1} size="display">Every frame keeps its warmth</Heading>
        <Text size="lg" variant="muted" className="max-w-xl">
          Twelve presets tuned on real film scans. Apply once, batch export a whole shoot and keep the original files untouched.
        </Text>
        <div className="flex flex-wrap items-center justify-center gap-3 pt-2">
          <Button size="lg">Try the presets</Button>
          <Button size="lg" variant="outline">Compare looks</Button>
        </div>
      </div>
      <div className="relative z-10 flex flex-col items-center gap-3">
        <Text size="sm" variant="muted">Works with</Text>
        <ul className="flex flex-wrap items-center justify-center gap-x-6 gap-y-2 text-[var(--color-foreground)]">
          {/* Your partner or customer logos go here */}
          <li className="text-sm font-medium">Vercel</li>
          <li className="text-sm font-medium">GitHub</li>
          <li className="text-sm font-medium">Cloudflare</li>
          <li className="text-sm font-medium">Astro</li>
        </ul>
      </div>
    </section>
  )
}
```

```tsx
import { LightLeak } from "@glinui/ui"

export function Variants() {
  return (
    <div data-glin-theme="dark" className="grid w-full gap-3 sm:grid-cols-3">
      <div className="relative isolate flex h-44 items-end overflow-hidden rounded-xl bg-[var(--surface-0)] p-3">
        <LightLeak intensity={0.6} />
        <span className="relative z-10 rounded-full bg-black/70 px-2.5 py-1 text-xs font-medium text-white">Default</span>
      </div>
      <div className="relative isolate flex h-44 items-end overflow-hidden rounded-xl bg-[var(--surface-0)] p-3">
        <LightLeak colors={["#06b6d4", "#3b82f6", "#8b5cf6"]} intensity={0.5} />
        <span className="relative z-10 rounded-full bg-black/70 px-2.5 py-1 text-xs font-medium text-white">Cool</span>
      </div>
      <div className="relative isolate flex h-44 items-end overflow-hidden rounded-xl bg-[var(--surface-0)] p-3">
        <LightLeak count={3} duration={14} intensity={0.5} />
        <span className="relative z-10 rounded-full bg-black/70 px-2.5 py-1 text-xs font-medium text-white">Three leaks</span>
      </div>
    </div>
  )
}
```

```tsx
import { LightLeak, Button, Heading, Text } from "@glinui/ui"

const stats = [
  ["Requests", "2.41M", "+8.2%"],
  ["p95 latency", "184 ms", "-12 ms"],
  ["Error rate", "0.03%", "-0.01%"]
]

export function UsageHeader() {
  return (
    <section data-glin-theme="dark" className="relative isolate flex min-h-[22rem] w-full flex-col justify-end gap-6 overflow-hidden rounded-xl bg-[var(--surface-0)] p-6 sm:p-8">
      <LightLeak intensity={0.5} />
      <div className="relative z-10 flex flex-wrap items-end justify-between gap-4">
        <div className="flex flex-col gap-1">
          <Text variant="eyebrow">Production, last 24 hours</Text>
          <Heading level={2} size="md">API overview</Heading>
        </div>
        <div className="flex gap-2">
          <Button size="sm" variant="outline">Export CSV</Button>
          <Button size="sm">Create alert</Button>
        </div>
      </div>
      <dl className="relative z-10 grid gap-3 sm:grid-cols-3">
        {stats.map(([label, value, delta]) => (
          <div key={label} className="rounded-xl border border-[var(--line-soft)] bg-[var(--surface-1)] p-4">
            <dt className="text-xs text-[var(--color-muted)]">{label}</dt>
            <dd className="mt-1 text-2xl font-semibold tabular-nums text-[var(--color-foreground)]">{value}</dd>
            <dd className="text-xs text-[var(--tone-success-text)]">{delta} vs yesterday</dd>
          </div>
        ))}
      </dl>
    </section>
  )
}
```

## Props

### LightLeakProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `blur?` | `number` | `60` | Blur amount in px |
| `colors?` | `string[]` | `["var(--tone-warning)", "var(--tone-d...` | Colors for the light leaks. Defaults come from theme tokens. |
| `count?` | `number` | `3` | Number of light leak layers |
| `duration?` | `number` | `6` | Animation duration in seconds |
| `intensity?` | `number` | `0.3` | Intensity/opacity (0-1) |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Renders with `aria-hidden`, invisible to assistive technologies.
- Purely decorative.
- Reduced motion: Animations are paused via `motion-reduce:[animation:none]`.

---

# Ripple

> Concentric expanding rings radiating from center for decorative backgrounds.

- id: `ripple`
- type: signature
- category: Backgrounds
- tags: signature
- docs: https://glinui.com/docs/components/ripple
- markdown: https://glinui.com/md/ripple.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add ripple
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/ripple.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Ripple } from "@glinui/ui"
```

## Usage

```tsx
import { Ripple } from "@glinui/ui"

export function RippleDemo() {
  return (
    <div className="relative flex h-72 w-full items-center justify-center overflow-hidden rounded-xl border border-[var(--color-border)] bg-[var(--surface-1)]">
      <span className="z-10 text-sm font-medium">Ripple</span>
      <Ripple />
    </div>
  )
}
```

```tsx
import { Ripple } from "@glinui/ui"

export function RippleGlassDemo() {
  return (
    <div className="relative flex h-48 w-full items-center justify-center overflow-hidden rounded-xl border border-[var(--glass-border)] bg-[var(--glass-readable)] backdrop-blur-xl">
      <span className="z-10 text-sm font-medium">Glass Ripple</span>
      <Ripple variant="glass" count={4} />
    </div>
  )
}
```

```tsx
import { Ripple } from "@glinui/ui"

export function RippleAccentDemo() {
  return (
    <div className="relative flex h-48 w-full items-center justify-center overflow-hidden rounded-xl border border-[var(--color-border)] bg-[var(--surface-1)]">
      <span className="z-10 text-sm font-medium">Accent</span>
      <Ripple variant="accent" count={5} duration={3} />
    </div>
  )
}
```

## Props

### RippleProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `count?` | `number` | `3` |  |
| `delay?` | `number` | `0.4` |  |
| `duration?` | `number` | `2` |  |
| `variant?` | `"default" \| "glass" \| "accent"` | `"default"` | Variant option from rippleVariants. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`, `glass`, `accent`.

## Accessibility

- Ripple is purely decorative with `pointer-events-none`.
- No interactive or focusable elements.
- Reduced motion: Ring animations use `motion-safe:animate-[...]` / `motion-reduce:hidden`. Under `prefers-reduced-motion`, rings are hidden entirely.

---

# Animated Beam

> A gradient beam that travels between two elements.

- id: `animated-beam`
- type: primitive
- category: Backgrounds
- tags: primitive, adapted
- docs: https://glinui.com/docs/components/radix/animated-beam
- markdown: https://glinui.com/md/animated-beam.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add animated-beam
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/animated-beam.json
```

Package:

```bash
npm install @glinui/ui @glinui/motion @glinui/tokens
```

## Import

```tsx
import { AnimatedBeam, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider } from "@glinui/ui"
```

## Usage

Adapted from Animated Beam by Magic UI (MIT). Glin UI measures the SVG path and travels a gradient dash along it with the Web Animations API instead of the motion library, observes the container and both anchors with ResizeObserver (the original only watched the container), coalesces updates with requestAnimationFrame, mirrors x offsets in RTL, uses collision-free gradient ids, and falls back to a static line.

The container must be positioned (relative) and contain both anchors. Render the beam after the anchors, with the same refs. The beam draws in the container coordinate space, so avoid transforms on the container.

The three demos use only Phosphor icons, never brand logos.

Engines: the `engine` prop is not applicable. SVG path gradient measured from layout; path driven, engines do not apply.

Link two anchors with a curved beam.

```tsx
import { BrandIcon } from "@/components/brand/brand-icon"
import { useRef } from "react"
import { Lightning } from "@phosphor-icons/react"
import { AnimatedBeam } from "@glinui/ui"

export function Demo() {
  const containerRef = useRef<HTMLDivElement>(null)
  const githubRef = useRef<HTMLDivElement>(null)
  const vercelRef = useRef<HTMLDivElement>(null)
  const cloudflareRef = useRef<HTMLDivElement>(null)
  const hubRef = useRef<HTMLDivElement>(null)
  const node = "grid size-12 place-items-center rounded-full border border-[var(--color-border)] bg-[var(--surface-1)]"
  return (
    <div ref={containerRef} className="relative mx-auto flex h-64 w-full max-w-md items-center justify-between overflow-hidden p-6">
      <div className="flex flex-col gap-6">
        <div ref={githubRef} className={node}><BrandIcon name="github" size="md" /></div>
        <div ref={vercelRef} className={node}><BrandIcon name="vercel" size="md" /></div>
        <div ref={cloudflareRef} className={node}><BrandIcon name="cloudflare" size="md" /></div>
      </div>
      <div ref={hubRef} className={`${node} size-16`}>
        <Lightning className="size-7 text-[var(--color-accent)]" aria-hidden />
      </div>
      <AnimatedBeam containerRef={containerRef} fromRef={githubRef} toRef={hubRef} curvature={-30} />
      <AnimatedBeam containerRef={containerRef} fromRef={vercelRef} toRef={hubRef} delay={0.6} />
      <AnimatedBeam containerRef={containerRef} fromRef={cloudflareRef} toRef={hubRef} curvature={30} delay={1.2} />
    </div>
  )
}
```

### Reverse

Travel from the right anchor to the left.

```tsx
<AnimatedBeam containerRef={container} fromRef={a} toRef={b} reverse />
```

### Integration hub

Several beams share one container, staggered with delay.

```tsx
<AnimatedBeam containerRef={container} fromRef={top} toRef={hub} curvature={-40} />
<AnimatedBeam containerRef={container} fromRef={bottom} toRef={hub} curvature={40} delay={0.6} />
<AnimatedBeam containerRef={container} fromRef={hub} toRef={out} delay={1.2} />
```

## Props

### AnimatedBeamProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `beamLength?` | `number` | `0.35` | Length of the travelling segment as a share of the path, 0.05 to 1. |
| `containerRef` | `React.RefObject<HTMLElement \| null>` |  | Positioned (relative) element that contains both anchors. The beam is drawn in it. |
| `curvature?` | `number` | `0` | Upward bend of the curve in px. Negative bends downward. |
| `delay?` | `number` | `0` | Seconds before the first pass. |
| `duration?` | `number` | `4` | Seconds for one pass. |
| `endXOffset?` | `number` | `0` |  |
| `endYOffset?` | `number` | `0` |  |
| `fromRef` | `React.RefObject<HTMLElement \| null>` |  |  |
| `gradientStartColor?` | `string` | `"var(--color-accent)"` |  |
| `gradientStopColor?` | `string` | `"color-mix(in oklab, var(--color-acce...` |  |
| `pathColor?` | `string` | `"var(--line-soft, var(--color-border))"` | Track color. Defaults to the soft line token. |
| `pathOpacity?` | `number` | `1` |  |
| `pathWidth?` | `number` | `2` |  |
| `repeatDelay?` | `number` | `0` | Seconds to rest between passes. |
| `reverse?` | `boolean` | `false` | Travel from `toRef` to `fromRef`. |
| `startXOffset?` | `number` | `0` |  |
| `startYOffset?` | `number` | `0` |  |
| `toRef` | `React.RefObject<HTMLElement \| null>` |  |  |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Decorative connector: aria-hidden, not focusable, pointer-events none.
- If the connection carries meaning, state it in text next to the anchors.
- The track keeps its contrast with the line token and never overlaps text.

ARIA:

- `aria-hidden="true"` on the svg

- Reduced motion: At motion level full a gradient segment travels the path. With prefers-reduced-motion or level none or subtle, the beam is a static gradient line. It also pauses offscreen and in background tabs.

## Provenance

Adapted from Magic UI (MIT, Copyright (c) Magic UI). Upstream: https://magicui.design/docs/components/animated-beam. Restyled to Glin tokens with accessibility and reduced motion review. Keep the attribution when you copy this component.

---

# Card

> Flexible surface container for grouped content.

- id: `card`
- type: primitive
- category: Cards and borders
- tags: primitive
- docs: https://glinui.com/docs/components/radix/card
- markdown: https://glinui.com/md/card.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add card
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/card.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { LIFT_SURFACE, Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter, SURFACE_VARIANTS } from "@glinui/ui"
```

## Usage

Omit `variant` and the card follows the ambient style: the glinr lift look (gradient hairline ring, tonal face) with no extra props.

```tsx
import { Button, Badge, Card } from "@glinui/ui"

export function Demo() {
  return (
    <Card>
      <PricingBody />
    </Card>
  )
}
```

### Variants

The full vocabulary across tones in both theme scopes. glinr is the default, plain is the flat shadcn card, solid is a neutral tonal face, glass is opt-in.

```tsx
import { Card } from "@glinui/ui"

<Card variant="glinr" />
<Card variant="plain" />
<Card variant="solid" />
<Card variant="soft" tone="accent" />
<Card variant="outline" />
<Card variant="ghost" />
<Card variant="gradient" />
<Card variant="glass" />
```

### Glass on a backdrop

Four surfaces over a vivid backdrop. Glass needs a backdrop to read as glass.

```tsx
import { Card } from "@glinui/ui"

<Card variant="glinr" />
<Card variant="plain" />
<Card variant="solid" />
<Card variant="glass" />
```

## Props

### CardContentProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `inset?` | `boolean` |  | Recessed well with the concentric inner radius, for code, lists and inputs. |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from cardSectionVariants. |

### CardDescriptionProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className?` | `string` |  | Additional class names for description text. |

### CardFooterProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from cardSectionVariants. |

### CardHeaderProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from cardSectionVariants. |
| `variant?` | `"default" \| "strip"` | `"default"` | `strip` renders a raised header band that bleeds to the card edges (glinr and solid cards). |

### CardProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `elevation?` | `unknown` |  | Variant option from cardVariants. |
| `face?` | `unknown` |  | Variant option from cardVariants. |
| `inset?` | `boolean` |  | Render a recessed well instead of a raised surface. |
| `interactive?` | `boolean` |  | Adds hover lift and a pointer cursor. Keyboard behavior stays with the consumer. |
| `ring?` | `"default" \| "hot" \| "brand"` |  | Variant option from cardVariants. |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from cardVariants. |
| `tone?` | `SurfaceTone` | `"neutral"` | Tone for soft, outline, ghost, gradient and glass. |
| `variant?` | `CardVariant \| null` | `"default"` | Surface look. Omitted (or `default`) follows the ambient design style: glinr, plain or glass. `glinr` lift shell, `plain` flat shadcn car... |

### CardSectionProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from cardSectionVariants. |

### CardTitleProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className?` | `string` |  | Additional class names for title text. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`, `strip`.

## Accessibility

- Semantic `<div>` containers.
- Use `CardTitle` for heading hierarchy.
- Add landmark roles if card represents a section.
- Card uses semantic section content you provide.
- Prefer heading levels that match page hierarchy.

ARIA:

- Semantic divs
- Heading hierarchy via CardTitle

- Reduced motion: No animation dependencies. Card supports reduced-motion fallback for transition-heavy states.

---

# Glass Card

> Frosted card with depth-aware blur, refraction edge highlights, and elevation transitions.

- id: `glass-card`
- type: signature
- category: Cards and borders
- tags: signature
- docs: https://glinui.com/docs/components/glass-card
- markdown: https://glinui.com/md/glass-card.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add glass-card
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/glass-card.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { GlassCard, GlassCardHeader, GlassCardContent, GlassCardFooter } from "@glinui/ui"
```

## Usage

```tsx
import { GlassCard } from "@glinui/ui"

export function GlassCardDemo() {
  return (
    <GlassCard>
      <ProfileBody />
    </GlassCard>
  )
}
```

```tsx
import { GlassCard } from "@glinui/ui"

// Omit variant to follow the ambient style (glinr by default).
export function GlassCardVariants() {
  return (
    <>
      <GlassCard variant="glinr">
        ...
      </GlassCard>
      <GlassCard variant="plain">
        ...
      </GlassCard>
      <GlassCard variant="solid">
        ...
      </GlassCard>
      <GlassCard variant="glass">
        ...
      </GlassCard>
    </>
  )
}
```

```tsx
import { GlassCard } from "@glinui/ui"

export function GlassCardTones() {
  return (
    <GlassCard variant="soft" tone="success">
      ...
    </GlassCard>
  )
}
```

## Props

### GlassCardProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `hoverLift?` | `boolean` | `true` | Lift on hover. Default true. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- GlassCard renders a ``, add semantic structure inside (headings, paragraphs).
- Ensure text contrast meets WCAG AA 4.5:1 on glass surfaces.
- Reduced motion: Hover elevation transitions respect `prefers-reduced-motion` and disable `transform` changes.

---

# Depth Card

> Parallax tilt card with layered glass planes and glare effect on hover.

- id: `depth-card`
- type: signature
- category: Cards and borders
- tags: signature
- docs: https://glinui.com/docs/components/depth-card
- markdown: https://glinui.com/md/depth-card.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add depth-card
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/depth-card.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { DepthLayer, DepthCard, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider } from "@glinui/ui"
```

## Usage

```tsx
import { DepthCard, DepthLayer } from "@glinui/ui"

export function DepthCardDemo() {
  return (
    <DepthCard autoPlay>
      <DepthLayer depth={4}>{/* floats highest */}</DepthLayer>
      <DepthLayer depth={2}>{/* floats lower */}</DepthLayer>
    </DepthCard>
  )
}
```

```tsx
import { DepthCard, DepthLayer } from "@glinui/ui"

// Omit variant to follow the ambient style (glinr by default).
export function DepthCardVariants() {
  return (
    <>
      <DepthCard variant="glinr">
        ...
      </DepthCard>
      <DepthCard variant="plain">
        ...
      </DepthCard>
      <DepthCard variant="solid">
        ...
      </DepthCard>
      <DepthCard variant="glass">
        ...
      </DepthCard>
    </>
  )
}
```

```tsx
import { DepthCard, DepthLayer } from "@glinui/ui"

export function DepthCardTones() {
  return (
    <DepthCard variant="soft" tone="success">
      ...
    </DepthCard>
  )
}
```

## Props

### DepthCardProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `autoPlay?` | `boolean` | `false` | Runs a slow looping synthetic pointer so the tilt, glare and layer parallax are visible without hovering (demos, screenshots, touch). Nee... |
| `glare?` | `boolean` | `true` | Glare effect |
| `glareOpacity?` | `number` | `0.35` | Glare max opacity |
| `hoverScale?` | `number` | `1.02` | Scale on hover |
| `maxTilt?` | `number` | `15` | Maximum tilt angle in degrees |
| `perspective?` | `number` | `800` | Perspective distance in px |

### DepthLayerProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `depth?` | `keyof typeof LAYER_DEPTH` | `2` | How far the layer floats above the card face (1 closest, 4 highest). |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- The glare overlay is `aria-hidden="true"`, invisible to assistive technologies.
- The card itself is a standard `div` with no implicit role; add `role` and keyboard handlers as needed.
- Content inside the card remains fully accessible.
- Reduced motion: When `prefers-reduced-motion: reduce` is active, the tilt transform is disabled via `motion-reduce:transform-none` and the glare layer is hidden via `motion-reduce:hidden`.

---

# Spotlight Card

> Card with cursor-tracked radial spotlight effect on hover.

- id: `spotlight-card`
- type: signature
- category: Cards and borders
- tags: signature
- docs: https://glinui.com/docs/components/spotlight-card
- markdown: https://glinui.com/md/spotlight-card.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add spotlight-card
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/spotlight-card.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { SpotlightCard, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider } from "@glinui/ui"
```

## Usage

```tsx
import { SpotlightCard } from "@glinui/ui"

export function SpotlightCardDemo() {
  return (
    <SpotlightCard autoPlay>
      <FeatureBody title="Instant previews" text="Every pull request gets a live URL." />
    </SpotlightCard>
  )
}
```

```tsx
import { SpotlightCard } from "@glinui/ui"

// Omit variant to follow the ambient style (glinr by default).
export function SpotlightCardVariants() {
  return (
    <>
      <SpotlightCard variant="glinr">
        ...
      </SpotlightCard>
      <SpotlightCard variant="plain">
        ...
      </SpotlightCard>
      <SpotlightCard variant="solid">
        ...
      </SpotlightCard>
      <SpotlightCard variant="glass">
        ...
      </SpotlightCard>
    </>
  )
}
```

```tsx
import { SpotlightCard } from "@glinui/ui"

export function SpotlightCardTones() {
  return (
    <SpotlightCard spotlightClassName="[background:radial-gradient(var(--spot-size,300px)_circle_at_var(--spot-x,_50%)_var(--spot-y,_50%),color-mix(in_oklab,var(--tone-success)_34%,transparent),transparent_70%)]">
      ...
    </SpotlightCard>
  )
}
```

## Props

### SpotlightCardProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `autoPlay?` | `boolean` | `false` | Runs a slow looping synthetic pointer so the spotlight is visible without hovering (demos, screenshots, touch). Off at reduced motion. A ... |
| `spotlightClassName?` | `string` |  |  |
| `spotlightSize?` | `number` | `300` | Spotlight radius in pixels. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- The spotlight overlay carries `aria-hidden="true"` and `pointer-events-none` so it is invisible to assistive technology and cannot intercept interactions.
- All content inside the card remains fully keyboard-accessible and semantically structured.
- `SpotlightCard` does not modify focus behavior, interactive children (buttons, links) work as expected.
- Reduced motion: The spotlight overlay is hidden entirely when `prefers-reduced-motion: reduce` is set via `motion-reduce:hidden`. The underlying `Card` hover transition (`transform`, `box-shadow`) is also disabled via `motion-reduce:transition-none` and `motion-reduce:hover:translate-y-0`, ensuring zero motion for users who prefer it.

---

# Magic Card

> Card whose border and surface light up under the pointer or keyboard focus.

- id: `magic-card`
- type: primitive
- category: Cards and borders
- tags: primitive, adapted
- docs: https://glinui.com/docs/components/radix/magic-card
- markdown: https://glinui.com/md/magic-card.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add magic-card
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/magic-card.json
```

Package:

```bash
npm install @glinui/ui @glinui/motion @glinui/tokens
```

## Import

```tsx
import { MagicCard, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider } from "@glinui/ui"
```

## Usage

Adapted from Magic Card by Magic UI (MIT). Modified: motion and next-themes removed, pointer tracking writes CSS variables from a rAF (zero React renders per move), colors come from tokens so dark mode follows the theme, keyboard focus lights the card, and a glass variant was added.

Overlap verdict versus SpotlightCard: about 40 percent. SpotlightCard is a glass-only soft spotlight. MagicCard also lights the border, works on the solid token surface and activates on keyboard focus, so both stay. Use SpotlightCard for a pure glass glow and MagicCard for border-follow grids.

The pointer effect only runs on fine pointers `(hover: hover) and (pointer: fine)`. Touch and coarse pointers get a static card.

The border and surface light up under the pointer. `autoPlay` loops a synthetic pointer so you can see it without hovering.

```tsx
import { MagicCard } from "@glinui/ui"

export function Demo() {
  return (
    <MagicCard autoPlay className="w-72">
      <PricingCard />
    </MagicCard>
  )
}
```

### Variants

glinr is the default, plain is flat shadcn, solid is a neutral tonal face, glass is opt-in and needs a backdrop.

```tsx
import { MagicCard } from "@glinui/ui"

// Omit `variant` to follow the ambient style (glinr by default).
export function MagicCardVariants() {
  return (
    <>
      <MagicCard variant="glinr">
        ...
      </MagicCard>
      <MagicCard variant="plain">
        ...
      </MagicCard>
      <MagicCard variant="solid">
        ...
      </MagicCard>
      <MagicCard variant="glass">
        ...
      </MagicCard>
    </>
  )
}
```

### Colors

`gradientFrom`, `gradientTo` and `gradientColor` take any token.

```tsx
import { MagicCard } from "@glinui/ui"

export function MagicCardTones() {
  return (
    <MagicCard gradientFrom="var(--tone-success)" gradientColor="color-mix(in oklab, var(--tone-success) 24%, transparent)">
      ...
    </MagicCard>
  )
}
```

## Props

### MagicCardProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `autoPlay?` | `boolean` | `false` | Runs a slow looping synthetic pointer so the highlight is visible without hovering (demos, screenshots, touch). Needs motion level full. ... |
| `gradientColor?` | `string` |  | Spotlight fill. Defaults to a soft tint of the accent token. |
| `gradientFrom?` | `string` |  | Border highlight start color. Defaults to the accent token. |
| `gradientSize?` | `number` | `280` | Radius in pixels of the spotlight and border highlight. |
| `gradientTo?` | `string` |  | Border highlight end color. Defaults to the signal token. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Decorative layers are aria-hidden and pointer-events-none, so nested links and buttons stay clickable.
- Content sits above the layers in DOM and paint order. Reading order is untouched.
- Keyboard focus inside the card lights it from the center, so the effect is not pointer only.

ARIA:

- `data-active` mirrors the lit state for styling
- Decorative spans use `aria-hidden="true"`

- Reduced motion: With motion level none, subtle or prefers-reduced-motion the card is fully static: no tracking, no highlight layers shown.

## Provenance

Adapted from Magic UI (MIT, Copyright (c) Magic UI). Upstream: https://magicui.design/docs/components/magic-card. Restyled to Glin tokens with accessibility and reduced motion review. Keep the attribution when you copy this component.

---

# Neon Gradient Card

> Card with an animated neon gradient ring and soft glow.

- id: `neon-gradient-card`
- type: primitive
- category: Cards and borders
- tags: primitive, adapted
- docs: https://glinui.com/docs/components/radix/neon-gradient-card
- markdown: https://glinui.com/md/neon-gradient-card.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add neon-gradient-card
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/neon-gradient-card.json
```

Package:

```bash
npm install @glinui/ui @glinui/motion @glinui/tokens
```

## Import

```tsx
import { NeonGradientCard, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider, SURFACE_VARIANTS, SURFACE_TONES, SURFACE_ELEVATIONS, SURFACE_VARIANT_ALIASES } from "@glinui/ui"
```

## Usage

Adapted from Neon Gradient Card by Magic UI (MIT). Modified: the ResizeObserver and width variables are gone (the ring is plain padding so it follows content), colors default to the accent and signal tokens, the gradient is animated through the Web Animations API only at motion level full, and a glass variant was added.

Improvements: one blur layer (smaller on phones), a static ring instead of the glow when motion is none, forced-colors fallback border, and an inner surface on the background token so text keeps contrast.

An animated neon ring and soft glow around a pricing card.

```tsx
import { NeonGradientCard } from "@glinui/ui"

export function Demo() {
  return (
    <NeonGradientCard className="w-72">
      <PricingCard />
    </NeonGradientCard>
  )
}
```

### Variants

glinr is the default, plain is flat shadcn, solid is a neutral tonal face, glass is opt-in and needs a backdrop.

```tsx
import { NeonGradientCard } from "@glinui/ui"

// Omit `variant` to follow the ambient style (glinr by default).
export function NeonGradientCardVariants() {
  return (
    <>
      <NeonGradientCard variant="glinr">
        ...
      </NeonGradientCard>
      <NeonGradientCard variant="plain">
        ...
      </NeonGradientCard>
      <NeonGradientCard variant="solid">
        ...
      </NeonGradientCard>
      <NeonGradientCard variant="glass">
        ...
      </NeonGradientCard>
    </>
  )
}
```

### Colors

`neonColors` takes any two tokens or colors.

```tsx
import { NeonGradientCard } from "@glinui/ui"

export function NeonGradientCardTones() {
  return (
    <NeonGradientCard neonColors={{ firstColor: "var(--tone-success)", secondColor: "var(--color-accent)" }}>
      ...
    </NeonGradientCard>
  )
}
```

## Props

### NeonGradientCardProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `borderRadius?` | `number` | `20` | Outer corner radius in pixels. |
| `borderSize?` | `number` | `2` | Ring thickness in pixels. |
| `contentClassName?` | `string` |  | Class for the inner content face. |
| `duration?` | `number` | `6` | Seconds per gradient cycle. |
| `neonColors?` | `Partial<NeonColors>` |  | Gradient colors. Default to the accent and signal tokens. |
| `variant?` | `NeonVariant \| null` |  | Face under the neon ring. Omitted follows the ambient style (glinr by default). `glass` is opt-in. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Ring and glow are aria-hidden decorations. Text lives on the background token face for reliable contrast.
- Under forced-colors the layers are hidden and a CanvasText border is used.
- Nothing depends on the animation.

ARIA:

- Decorative layers use `aria-hidden="true"`
- `data-animated` reflects the running state

- Reduced motion: At motion level none, subtle or with prefers-reduced-motion the gradient stops, and the blurred glow is removed leaving a static ring.

## Provenance

Adapted from Magic UI (MIT, Copyright (c) Magic UI). Upstream: https://magicui.design/docs/components/neon-gradient-card. Restyled to Glin tokens with accessibility and reduced motion review. Keep the attribution when you copy this component.

---

# Glow Border

> Rotating conic-gradient glow effect around container border.

- id: `glow-border`
- type: signature
- category: Cards and borders
- tags: signature
- docs: https://glinui.com/docs/components/glow-border
- markdown: https://glinui.com/md/glow-border.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add glow-border
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/glow-border.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { GlowBorder, SURFACE_VARIANTS, SURFACE_TONES, SURFACE_ELEVATIONS, SURFACE_VARIANT_ALIASES, STYLE_DEFAULT_VARIANT, GlinProvider, GLIN_MOTIONS } from "@glinui/ui"
```

## Usage

```tsx
import { GlowBorder } from "@glinui/ui"

export function GlowBorderDemo() {
  return (
    <GlowBorder glowSize={3} borderRadius="1.25rem">
      <div className="p-6"><IntegrationBody /></div>
    </GlowBorder>
  )
}
```

```tsx
import { GlowBorder } from "@glinui/ui"

// Omit variant to follow the ambient style (glinr by default).
export function GlowBorderVariants() {
  return (
    <>
      <GlowBorder variant="glinr" glowSize={3}>
        ...
      </GlowBorder>
      <GlowBorder variant="plain" glowSize={3}>
        ...
      </GlowBorder>
      <GlowBorder variant="solid" glowSize={3}>
        ...
      </GlowBorder>
      <GlowBorder variant="glass" glowSize={3}>
        ...
      </GlowBorder>
    </>
  )
}
```

```tsx
import { GlowBorder } from "@glinui/ui"

export function GlowBorderTones() {
  return (
    <GlowBorder glowColor="var(--tone-success)" glowSize={3}>
      ...
    </GlowBorder>
  )
}
```

## Props

### GlowBorderProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `borderRadius?` | `string` | `"var(--radius-lg)"` | Border radius |
| `duration?` | `number` | `4` | Rotation duration in seconds |
| `glowColor?` | `string` | `"var(--color-accent)"` | Glow color |
| `glowSize?` | `number` | `2` | Glow spread in px |
| `variant?` | `SurfaceVariant \| "default" \| null` |  | Face inside the glow. Omitted follows the ambient style (glinr by default). `glass` is opt-in. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`.

## Accessibility

- The glow pseudo-element is purely decorative and carries `aria-hidden` semantics, it does not affect the accessibility tree.
- `GlowBorder` does not alter the focusability or tab order of its children.
- Keyboard navigation passes through to child content unchanged.
- Reduced motion: When `prefers-reduced-motion: reduce` is active, the rotating glow animation is hidden entirely so that users sensitive to motion are not affected.

---

# Border Beam

> Light beam that travels along the border of its container via CSS offset-path.

- id: `border-beam`
- type: signature
- category: Cards and borders
- tags: signature
- docs: https://glinui.com/docs/components/border-beam
- markdown: https://glinui.com/md/border-beam.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add border-beam
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/border-beam.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { BorderBeam } from "@glinui/ui"
```

## Usage

```tsx
import { BorderBeam, Card } from "@glinui/ui"

// Omit variant to follow the ambient style (glinr by default).
export function BorderBeamVariants() {
  return (
    <>
      <Card variant="glinr" className="relative">
  <BorderBeam size={180} />
        ...
      </Card>
      <Card variant="plain" className="relative">
  <BorderBeam size={180} />
        ...
      </Card>
      <Card variant="solid" className="relative">
  <BorderBeam size={180} />
        ...
      </Card>
      <Card variant="glass" className="relative">
  <BorderBeam size={180} />
        ...
      </Card>
    </>
  )
}
```

```tsx
import { BorderBeam, Card } from "@glinui/ui"

export function BorderBeamTones() {
  return (
    <Card className="relative">
  <BorderBeam colorFrom="var(--tone-success)" />
      ...
    </Card>
  )
}
```

```tsx
// Beam cards as metric tiles in a dashboard row.
import { BorderBeam, Card } from "@glinui/ui"

export function BorderBeamLayout() {
  return (
    <section className="grid gap-4 sm:grid-cols-3">
      ...
    </section>
  )
}
```

## Props

### BorderBeamProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `borderRadius?` | `string` |  |  |
| `colorFrom?` | `string` | `"var(--color-accent)"` |  |
| `colorTo?` | `string` | `"transparent"` |  |
| `delay?` | `number` | `0` |  |
| `duration?` | `number` | `6` |  |
| `size?` | `number` | `100` |  |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- `BorderBeam` is purely decorative and does not receive focus.
- No interactive elements, safe for screen readers.
- Reduced motion: The beam animation uses `motion-reduce:hidden`. Under `prefers-reduced-motion`, the beam is hidden entirely.

---

# Border Trail

> Glowing comet that travels along the border of a rounded container.

- id: `border-trail`
- type: primitive
- category: Cards and borders
- tags: primitive, adapted
- docs: https://glinui.com/docs/components/radix/border-trail
- markdown: https://glinui.com/md/border-trail.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add border-trail
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/border-trail.json
```

Package:

```bash
npm install @glinui/ui @glinui/motion @glinui/tokens
```

## Import

```tsx
import { BorderTrail, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider } from "@glinui/ui"
```

## Usage

Adapted from Border Trail by Motion Primitives (MIT). Modified: motion/react removed (the comet follows `offset-path: rect()` driven by the Web Animations API), token colors with a soft radial head, the path radius defaults to the parent's border radius, and a rotating conic ring is used where `offset-path: rect()` is unsupported.

The parent must be `relative` with a border radius, and should clip overflow. Distinct from BorderBeam (a dot) and ShineBorder (a drifting gradient): a short comet on a thin track.

Improvement over the original: no hardcoded zinc, offscreen and hidden tab pause, static corner glow at motion none, hidden under forced-colors.

A comet circles the card edge.

```tsx
import { BorderTrail, Card } from "@glinui/ui"

<Card className="relative overflow-hidden">
  <BorderTrail size={90} borderWidth={2} duration={6} />
  ...
</Card>
```

### Variants

Color sources per style.

```tsx
<BorderTrail variant="glass" borderWidth={2} />
```

### States

Custom color, length, radius and speed.

```tsx
<BorderTrail color="var(--color-signal-ok)" size={120} />
<BorderTrail radius={32} duration={3} borderWidth={3} size={50} />
```

## Props

### BorderTrailProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `borderWidth?` | `number` | `1` | Border thickness in pixels. |
| `color?` | `string` |  | Trail color. Defaults to the variant token. |
| `duration?` | `number` | `5` | Seconds per lap. |
| `radius?` | `number` |  | Corner radius of the path in pixels. Defaults to the parent border radius. |
| `size?` | `number` | `60` | Length of the glowing segment in pixels. |
| `variant?` | `"default" \| "plain" \| "glass"` | `"default"` | Variant option from borderTrailVariants. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`, `plain`, `glass`.

## Accessibility

- Purely decorative: aria-hidden, pointer-events-none, never focusable.
- Hidden under forced-colors so the real border shows.
- Pauses offscreen and while the tab is hidden.

ARIA:

- `aria-hidden="true"` on the layer
- `data-mode` reports `path` or `conic`, `data-animated` reports motion

- Reduced motion: The comet only travels at motion level full. Under motion none, subtle or prefers-reduced-motion it rests as a static glow at the top start corner.

## Provenance

Adapted from Motion Primitives (MIT, Copyright (c) 2024 ibelick). Upstream: https://motion-primitives.com/docs/border-trail. Restyled to Glin tokens with accessibility and reduced motion review. Keep the attribution when you copy this component.

---

# Prism Border

> Animated rainbow refraction border using a shifting linear gradient.

- id: `prism-border`
- type: signature
- category: Cards and borders
- tags: signature
- docs: https://glinui.com/docs/components/prism-border
- markdown: https://glinui.com/md/prism-border.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add prism-border
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/prism-border.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { PrismBorder } from "@glinui/ui"
```

## Usage

```tsx
import { PrismBorder, Card } from "@glinui/ui"

export function PrismBorderDemo() {
  return (
    <PrismBorder borderWidth={2} borderRadius="1.25rem">
      <Card className="rounded-[inherit]"><ProfileBody /></Card>
    </PrismBorder>
  )
}
```

```tsx
import { PrismBorder, Card } from "@glinui/ui"

// Omit variant to follow the ambient style (glinr by default).
export function PrismBorderVariants() {
  return (
    <>
      <PrismBorder borderWidth={2}>
  <Card variant="glinr" className="rounded-[inherit]">
        ...
        </Card>
</PrismBorder>
      <PrismBorder borderWidth={2}>
  <Card variant="plain" className="rounded-[inherit]">
        ...
        </Card>
</PrismBorder>
      <PrismBorder borderWidth={2}>
  <Card variant="solid" className="rounded-[inherit]">
        ...
        </Card>
</PrismBorder>
      <PrismBorder borderWidth={2}>
  <Card variant="glass" className="rounded-[inherit]">
        ...
        </Card>
</PrismBorder>
    </>
  )
}
```

```tsx
import { PrismBorder, Card } from "@glinui/ui"

export function PrismBorderTones() {
  return (
    <PrismBorder borderWidth={2} colors={["var(--tone-success)", "var(--color-accent)", "var(--tone-success)"]>
  <Card className="rounded-[inherit]">
      ...
      </Card>
</PrismBorder>
  )
}
```

## Props

### PrismBorderProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `borderRadius?` | `string` | `"0.75rem"` | Border radius |
| `borderWidth?` | `number` | `2` | Border width in px |
| `colors?` | `string[]` | `["#f43f5e", "#f97316", "#eab308", "#2...` | Custom gradient colors |
| `duration?` | `number` | `3` | Animation duration in seconds |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- The animated border element is `aria-hidden="true"`, invisible to assistive technologies.
- Content inside the border wrapper remains fully accessible.
- Reduced motion: The gradient animation is paused via `motion-reduce:[animation:none]`. A static gradient border remains visible.

---

# Shine Border

> Animated gradient edge that wraps any rounded container.

- id: `shine-border`
- type: primitive
- category: Cards and borders
- tags: primitive, adapted
- docs: https://glinui.com/docs/components/radix/shine-border
- markdown: https://glinui.com/md/shine-border.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add shine-border
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/shine-border.json
```

Package:

```bash
npm install @glinui/ui @glinui/motion @glinui/tokens
```

## Import

```tsx
import { ShineBorder, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider } from "@glinui/ui"
```

## Usage

Adapted from Shine Border by Magic UI (MIT). Modified: colors default to the accent token, the sweep runs through the Web Animations API only at motion level full, the gradient is mirrored in RTL and a glass variant was added.

ShineBorder differs from BorderBeam: the beam is a single travelling dot, the shine is a soft gradient that drifts around the whole edge. The parent must be `relative` and have a border radius, which the layer inherits.

Improvement over the original: no inline style object, no hardcoded black default, and the animation is removed from the DOM when motion is none or reduced.

Engines: the `engine` prop is not applicable. Looping css conic-gradient animation; not a reveal, so engines do not apply.

A soft gradient drifts around the edge of a login card.

```tsx
import { Button, Card, Input, ShineBorder } from "@glinui/ui"

export function Demo() {
  return (
    <Card className="relative w-full max-w-sm overflow-hidden p-6">
      <ShineBorder borderWidth={2} duration={8} />
      <form className="flex flex-col gap-4" onSubmit={(e) => e.preventDefault()}>
        <h2 className="text-lg font-semibold">Sign in</h2>
        <label className="flex flex-col gap-1.5 text-sm">
          Email
          <Input type="email" placeholder="you@company.com" autoComplete="email" />
        </label>
        <label className="flex flex-col gap-1.5 text-sm">
          Password
          <Input type="password" placeholder="At least 12 characters" autoComplete="current-password" />
        </label>
        <Button type="submit">Continue</Button>
      </form>
    </Card>
  )
}
```

### Variants

glinr is the default, plain is flat shadcn, solid is a neutral tonal face, glass is opt-in and needs a backdrop.

```tsx
import { ShineBorder, Card } from "@glinui/ui"

// Omit `variant` to follow the ambient style (glinr by default).
export function ShineBorderVariants() {
  return (
    <>
      <Card variant="glinr" className="relative">
        <ShineBorder borderWidth={2} />
        ...
      </Card>
      <Card variant="plain" className="relative">
        <ShineBorder borderWidth={2} />
        ...
      </Card>
      <Card variant="solid" className="relative">
        <ShineBorder borderWidth={2} />
        ...
      </Card>
      <Card variant="glass" className="relative">
        <ShineBorder borderWidth={2} />
        ...
      </Card>
    </>
  )
}
```

### Colors

`shineColor` takes one color or a list of tokens.

```tsx
import { ShineBorder, Card } from "@glinui/ui"

export function ShineBorderTones() {
  return (
    <Card className="relative">
      <ShineBorder shineColor={["var(--tone-success)", "var(--color-accent)"]} />
      ...
    </Card>
  )
}
```

## Props

### ShineBorderProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `borderWidth?` | `number` | `1` | Border thickness in pixels. |
| `duration?` | `number` | `14` | Seconds for one full sweep cycle. |
| `shineColor?` | `string \| string[]` |  | One color or a list of colors. Defaults to the accent token. |
| `variant?` | `"default" \| "plain" \| "glass"` | `"default"` | Variant option from shineBorderVariants. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`, `plain`, `glass`.

## Accessibility

- Purely decorative: aria-hidden and pointer-events-none, never receives focus or intercepts clicks.
- Hidden under forced-colors so the parent keeps its real border.
- No information is conveyed by the animation.

ARIA:

- `aria-hidden="true"` on the layer
- `data-animated` reflects whether the sweep is running

- Reduced motion: The sweep only runs when the Glin motion level is full and prefers-reduced-motion is off. Otherwise the border renders as a static gradient frame.

## Provenance

Adapted from Magic UI (MIT, Copyright (c) Magic UI). Upstream: https://magicui.design/docs/components/shine-border. Restyled to Glin tokens with accessibility and reduced motion review. Keep the attribution when you copy this component.

---

# Bento Grid

> Responsive bento layout of linked feature tiles.

- id: `bento-grid`
- type: primitive
- category: Cards and borders
- tags: primitive, adapted
- docs: https://glinui.com/docs/components/radix/bento-grid
- markdown: https://glinui.com/md/bento-grid.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add bento-grid
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/bento-grid.json
```

Package:

```bash
npm install @glinui/ui @glinui/motion @glinui/tokens
```

## Import

```tsx
import { BentoGrid, BentoCard, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider, SURFACE_VARIANTS, SURFACE_TONES, SURFACE_ELEVATIONS } from "@glinui/ui"
```

## Usage

Adapted from Bento Grid by Magic UI (MIT). Modified: a responsive 1, 2 and 3 column grid, the whole card is one real anchor when href is set, the CTA is keyboard reachable and always visible on touch, Phosphor arrow with RTL flip, lift and glass surfaces from the Card tokens.

The original nested a link button inside a div and revealed it on hover only, which keyboard users could not reach. Here the CTA is a styled span inside the single anchor, shown on hover, focus-visible and always on coarse pointers.

Engines: this component drives its main animation through the pluggable motion engine. Pass `engine` (css, motion or gsap), wrap a subtree in `MotionEngineProvider`, or set `data-glin-engine` on `<html>`. The css engine is built in and dependency free; motion and gsap are opt-in via `@glinui/motion/register/*`. `motion="none"` renders the final state and `subtle` is opacity only.

Five tiles of mixed size with real content.

```tsx
import { CheckCircle, Cube, Lightning, ShieldCheck } from "@phosphor-icons/react"
import { BentoCard, BentoGrid } from "@glinui/ui"

export function Demo() {
  return (
    <BentoGrid entrance className="max-w-3xl auto-rows-[minmax(10rem,auto)]">
      <BentoCard name="Realtime sync" description="Edits appear for everyone in under 100ms." Icon={Lightning} className="lg:col-span-2" />
      <BentoCard name="Audit log" description="Every change, with who and when." Icon={ShieldCheck} />
      <BentoCard name="Plugins" description="Extend the workspace with your own blocks." Icon={Cube} />
      <BentoCard name="SSO" description="SAML and SCIM on every paid plan." Icon={CheckCircle} className="lg:col-span-2" />
    </BentoGrid>
  )
}
```

### Variants

glinr is the default, plain is flat shadcn, solid is a neutral tonal face, glass is opt-in and needs a backdrop.

```tsx
import { BentoCard, BentoGrid } from "@glinui/ui"

// Omit `variant` to follow the ambient style (glinr by default).
export function BentoGridVariants() {
  return (
    <>
      <BentoCard variant="glinr" name="..." description="..." />
        ...
      
      <BentoCard variant="plain" name="..." description="..." />
        ...
      
      <BentoCard variant="solid" name="..." description="..." />
        ...
      
      <BentoCard variant="glass" name="..." description="..." />
        ...
      
    </>
  )
}
```

### Colors

Tile washes follow the tone tokens.

```tsx
import { BentoCard, BentoGrid } from "@glinui/ui"

export function BentoGridTones() {
  return (
    <BentoCard name="Success" description="..." background={<Wash tone="success" />} />
      ...
    
  )
}
```

## Props

### BentoCardProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `background?` | `React.ReactNode` |  | Decorative background layer (pattern, gradient, illustration). Hidden from assistive tech. |
| `cta?` | `string` |  | Call to action label, shown with an arrow when `href` is set. |
| `description` | `string` |  |  |
| `headingLevel?` | `2 \| 3 \| 4` | `3` | Heading level for the card name. |
| `href?` | `string` |  | When set the whole card is a single anchor. |
| `Icon?` | `React.ElementType<{ className?: string; "aria-hidden"?: boolean }>` |  | Icon component (Phosphor icons work). Rendered decoratively. |
| `name` | `string` |  | Card title, rendered as a heading. |
| `rel?` | `string` |  |  |
| `target?` | `React.HTMLAttributeAnchorTarget` |  |  |
| `variant?` | `SurfaceVariant \| "default" \| null` |  | Surface look. Omitted follows the ambient style (glinr by default). `glass` is opt-in and needs a backdrop. |

### BentoGridProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `duration?` | `number` |  | Per-card duration in ms. |
| `engine?` | `EngineName` |  | Engine override: `css` (default), `motion`, `gsap` or a registered custom engine. |
| `entrance?` | `boolean` | `false` | Reveal the cards in sequence when the grid enters the viewport. Off by default. |
| `immediate?` | `boolean` | `false` | Play on mount instead of waiting for the viewport. |
| `motion?` | `MotionLevel` |  | Motion override. `none` renders the static final state, `subtle` is opacity only. |
| `order?` | `StaggerDirection` | `"forward"` | Order the cards appear in. Default `forward`. |
| `step?` | `number` | `70` | Delay between cards in ms. Default 70. |
| `threshold?` | `number` |  | Visible fraction required to trigger. Default 0.15. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`.

## Accessibility

- Cards with href are single anchors, so one tab stop per card, with a visible focus ring.
- Decorative backgrounds and icons are aria-hidden.
- CTA is available without hover: focus reveals it on fine pointers, touch always shows it.

Keyboard:

| Key | Action |
| --- | --- |
| Tab | Moves between linked cards. |
| Enter | Follows the focused card link. |

ARIA:

- Card name is a real heading
- Icon and background are `aria-hidden`

- Reduced motion: The hover lift, icon scale and CTA slide are removed with prefers-reduced-motion or motion level none. At level none the CTA is always visible.

## Provenance

Adapted from Magic UI (MIT, Copyright (c) Magic UI). Upstream: https://magicui.design/docs/components/bento-grid. Restyled to Glin tokens with accessibility and reduced motion review. Keep the attribution when you copy this component.

---

# Icon Frame

> Consistent framed surface for icon glyphs and short initials.

- id: `icon-frame`
- type: primitive
- category: Cards and borders
- tags: primitive
- docs: https://glinui.com/docs/components/radix/icon-frame
- markdown: https://glinui.com/md/icon-frame.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add icon-frame
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/icon-frame.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { IconFrame, SURFACE_VARIANTS, SURFACE_TONES, SURFACE_ELEVATIONS, SURFACE_VARIANT_ALIASES, STYLE_DEFAULT_VARIANT, GlinProvider, GLIN_MOTIONS } from "@glinui/ui"
```

## Usage

Feature cards led by tinted icon frames.

```tsx
import { Bug, ChartLineUp, Lightning, ShieldCheck } from "@phosphor-icons/react"
import { Card, IconFrame } from "@glinui/ui"

export function Demo() {
  const features = [
    { icon: Lightning, tone: "accent" as const, title: "Fast builds", text: "Incremental builds finish in under 8 seconds." },
    { icon: ShieldCheck, tone: "success" as const, title: "Secure by default", text: "Secrets are encrypted and rotated automatically." },
    { icon: ChartLineUp, tone: "info" as const, title: "Live metrics", text: "Latency and error rates update every minute." },
    { icon: Bug, tone: "danger" as const, title: "Error tracking", text: "Group crashes by release and assign an owner." }
  ]
  return (
    <div className="grid w-full max-w-3xl gap-4 sm:grid-cols-2">
      {features.map((feature) => (
        <Card key={feature.title} className="flex flex-row items-start gap-4">
          <IconFrame tone={feature.tone} size="lg"><feature.icon aria-hidden className="size-5" /></IconFrame>
          <div className="flex flex-col gap-1">
            <h3 className="text-sm font-semibold">{feature.title}</h3>
            <p className="text-sm text-[var(--color-muted)]">{feature.text}</p>
          </div>
        </Card>
      ))}
    </div>
  )
}
```

### Variants

The shared vocabulary. Omit `variant` for the ambient style (glinr).

```tsx
import { IconFrame } from "@glinui/ui"

<IconFrame variant="glinr" tone="accent"><Bell /></IconFrame>
```

### Tones

Soft frames in every tone.

```tsx
import { IconFrame } from "@glinui/ui"

<IconFrame variant="soft" tone="success"><Bell /></IconFrame>
```

## Props

### IconFrameProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from iconFrameVariants. |
| `tone?` | `SurfaceTone` | `"neutral"` | Tone for the icon color and tinted looks. |
| `variant?` | `IconFrameVariant \| null` |  | Omitted follows the ambient style (glinr by default). `glass` is opt-in and needs a backdrop. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Use `aria-hidden` when decorative.
- Add screen-reader text for meaningful icons.
- `IconFrame` is a decorative container. Icons inside it should have `aria-hidden="true"` when accompanied by visible text labels.
- When used as a standalone icon button (e.g., wrapped in a `<button>`), provide an `aria-label` on the button element.
- Text initials inside `IconFrame` should be supplemented with a surrounding `aria-label` or `title` for screen readers when used as an avatar.
- The frame itself carries no interactive semantics, wrap it in a `<button>` or `<a>` when interaction is needed.

ARIA:

- `aria-hidden="true"` for decorative usage

- Reduced motion: Frame transitions are color-only and respect reduced-motion settings. `IconFrame` is a static layout primitive with no animation. No reduced-motion considerations apply.

---

# Highlight Grid

> Hairline cell grid with one shared highlight that glides to the hovered, tapped or focused cell.

- id: `highlight-grid`
- type: primitive
- category: Cards and borders
- tags: primitive
- docs: https://glinui.com/docs/components/radix/highlight-grid
- markdown: https://glinui.com/md/highlight-grid.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add highlight-grid
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/highlight-grid.json
```

Package:

```bash
npm install @glinui/ui @glinui/motion @glinui/tokens
```

## Import

```tsx
import { HighlightGrid, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider, SURFACE_VARIANTS, SURFACE_TONES, SURFACE_ELEVATIONS, SURFACE_VARIANT_ALIASES } from "@glinui/ui"
```

## Usage

Our own design (clean-room, no upstream code). One highlight panel glides between hairline cells instead of every cell animating on its own.

The panel is measured against the grid with physical offsets, so mirrored RTL layouts work. A ResizeObserver keeps it aligned when the grid reflows.

Entering the grid from outside places the panel on the entry cell with no fly-in from a corner.

Six feature cells. Hover, tap or tab through them.

```tsx
import { HighlightGrid } from "@glinui/ui"

export function Demo() {
  return <HighlightGrid cells={features} cellRenderer={renderFeature} />
}
```

### Variants

glinr accent wash, plain neutral wash and glass.

```tsx
<HighlightGrid variant="plain" cells={cells} />
```

### States

Link cells with an href, reachable with the keyboard.

```tsx
<HighlightGrid columns={2} cells={cells.map((c) => ({ ...c, href: "#" + c.id }))} />
```

## Props

### HighlightGridProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `cellRenderer?` | `(cell: HighlightGridCell, state: HighlightGridCellState) => React.ReactNode` |  |  |
| `cells` | `HighlightGridCell[]` |  |  |
| `columns?` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `3` | Columns from the lg breakpoint up. Narrow screens use 1 or 2. |
| `variant?` | `HighlightGridVariant` |  | Highlight panel look. `glinr` is an accent wash with a soft border, `plain` a neutral wash, `glass` a blurred sheet. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- A list of cells with a roving tabindex. Arrow keys, Home and End move focus and the highlight follows.
- The panel is aria-hidden and pointer-events-none, so cells and links stay clickable.
- Touch: tapping a cell moves the highlight and it stays until you tap elsewhere.
- The highlight is never the only indicator, keyboard focus also shows a ring.

Keyboard:

| Key | Action |
| --- | --- |
| Arrow keys | Move between cells (left and right reversed in RTL, up and down follow the real column count). |
| Home / End | First or last cell. |
| Enter | Follows the link of a cell with href. |

ARIA:

- `role="list"` with list items
- Decorative panel uses `aria-hidden`

- Reduced motion: The glide, resize and fade only run at motion level full. Otherwise the highlight jumps to the new cell.

---

# Navigation Menu

> Site navigation with animated content panels, links and a shared viewport.

- id: `navigation-menu`
- type: primitive
- category: Navigation
- tags: primitive
- docs: https://glinui.com/docs/components/radix/navigation-menu
- markdown: https://glinui.com/md/navigation-menu.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add navigation-menu
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/navigation-menu.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { NavigationMenu, NavigationMenuList, NavigationMenuItem, NavigationMenuTrigger, NavigationMenuContent, NavigationMenuLink, NavigationMenuViewport, NavigationMenuIndicator } from "@glinui/ui"
```

## Usage

A site header with a mega menu opened by default. Each link pairs an icon with a short description.

```tsx
"use client"

import { ChartLineUp, Cube, Lightning, Plugs, ShieldCheck } from "@phosphor-icons/react"
import {
  Button,
  IconFrame,
  NavigationMenu,
  NavigationMenuContent,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  NavigationMenuTrigger,
  navigationMenuTriggerStyle
} from "@glinui/ui"

const MEGA = [
  { icon: ChartLineUp, title: "Analytics", text: "Funnels, cohorts and retention in one view." },
  { icon: Lightning, title: "Automation", text: "Trigger flows from product events." },
  { icon: ShieldCheck, title: "Access control", text: "Roles, SSO and audit logs for every team." },
  { icon: Plugs, title: "Integrations", text: "Sync with the tools your team already uses." }
]

export function NavMegaHero() {
  return (
    <div className="mx-auto min-h-80 w-full max-w-3xl">
      <header className="flex flex-wrap items-center justify-between gap-3 rounded-2xl border border-[var(--line-soft)] bg-[var(--surface-1)] px-4 py-2.5 [box-shadow:var(--elev-1)]">
        <div className="flex items-center gap-2 font-semibold">
          <IconFrame size="sm" tone="accent"><Cube aria-hidden="true" /></IconFrame>
          Lumen
        </div>
        <NavigationMenu aria-label="Main" defaultValue="products">
          <NavigationMenuList>
            <NavigationMenuItem value="products">
              <NavigationMenuTrigger>Products</NavigationMenuTrigger>
              <NavigationMenuContent>
                <div className="grid w-full gap-1 p-1 md:w-[34rem] md:grid-cols-2">
                  {MEGA.map(({ icon: Icon, title, text }) => (
                    <NavigationMenuLink key={title} href="#" className="flex items-start gap-3">
                      <IconFrame size="sm"><Icon aria-hidden="true" /></IconFrame>
                      <span className="grid gap-0.5">
                        <span className="text-sm font-medium">{title}</span>
                        <span className="text-xs leading-5 text-[var(--color-muted)]">{text}</span>
                      </span>
                    </NavigationMenuLink>
                  ))}
                </div>
              </NavigationMenuContent>
            </NavigationMenuItem>
            <NavigationMenuItem value="resources">
              <NavigationMenuTrigger>Resources</NavigationMenuTrigger>
              <NavigationMenuContent>
                <div className="grid w-56 gap-1">
                  <NavigationMenuLink href="#">Guides</NavigationMenuLink>
                  <NavigationMenuLink href="#">Changelog</NavigationMenuLink>
                </div>
              </NavigationMenuContent>
            </NavigationMenuItem>
            <NavigationMenuItem>
              <NavigationMenuLink href="#" className={navigationMenuTriggerStyle()}>Pricing</NavigationMenuLink>
            </NavigationMenuItem>
          </NavigationMenuList>
        </NavigationMenu>
        <div className="flex items-center gap-2">
          <Button size="sm" variant="ghost">Sign in</Button>
          <Button size="sm">Start free</Button>
        </div>
      </header>
    </div>
  )
}
```

### Inline panels

Pass viewport={false} to render each panel under its own trigger instead of a shared viewport.

```tsx
"use client"

import {
  NavigationMenu,
  NavigationMenuContent,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  NavigationMenuTrigger,
  navigationMenuTriggerStyle
} from "@glinui/ui"

export function NavInlineExample() {
  return (
    <div className="mx-auto min-h-56 w-full max-w-xl">
      <NavigationMenu aria-label="Docs" viewport={false} defaultValue="learn" className="max-w-none justify-start">
        <NavigationMenuList>
          <NavigationMenuItem value="learn" className="relative">
            <NavigationMenuTrigger>Learn</NavigationMenuTrigger>
            <NavigationMenuContent>
              <ul className="grid w-60 gap-1 p-1">
                <li><NavigationMenuLink href="#"><span className="block text-sm font-medium">Quickstart</span><span className="block text-xs text-[var(--color-muted)]">Ship a first page in 5 minutes.</span></NavigationMenuLink></li>
                <li><NavigationMenuLink href="#"><span className="block text-sm font-medium">Theming</span><span className="block text-xs text-[var(--color-muted)]">Tokens, modes and variants.</span></NavigationMenuLink></li>
              </ul>
            </NavigationMenuContent>
          </NavigationMenuItem>
          <NavigationMenuItem>
            <NavigationMenuLink href="#" className={navigationMenuTriggerStyle()}>Components</NavigationMenuLink>
          </NavigationMenuItem>
          <NavigationMenuItem>
            <NavigationMenuLink href="#" className={navigationMenuTriggerStyle()}>Examples</NavigationMenuLink>
          </NavigationMenuItem>
        </NavigationMenuList>
      </NavigationMenu>
    </div>
  )
}
```

### Glass (opt-in)

Glass is opt-in and needs a colourful or photographic backdrop. Pick one in the stage header.

```tsx
import { NavigationMenu, NavigationMenuContent, NavigationMenuItem, NavigationMenuLink, NavigationMenuList, NavigationMenuTrigger, navigationMenuTriggerStyle } from "@glinui/ui"

export function Demo() {
  return (
    <NavigationMenu aria-label="Main" variant="glass">
      <NavigationMenuList>
        <NavigationMenuItem>
          <NavigationMenuTrigger>Products</NavigationMenuTrigger>
          <NavigationMenuContent>
            <div className="grid w-64 gap-1">
              <NavigationMenuLink href="#">Analytics</NavigationMenuLink>
              <NavigationMenuLink href="#">Automation</NavigationMenuLink>
            </div>
          </NavigationMenuContent>
        </NavigationMenuItem>
        <NavigationMenuItem>
          <NavigationMenuLink href="#" className={navigationMenuTriggerStyle()}>Docs</NavigationMenuLink>
        </NavigationMenuItem>
      </NavigationMenuList>
    </NavigationMenu>
  )
}
```

## Props

### NavigationMenuProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant?` | `NavigationMenuVariant` |  | Surface look of the viewport panel and trigger pills. Omit for the ambient design style (glinr by default). |
| `viewport?` | `boolean` | `true` | Render content in a shared animated viewport (default) or inline per item. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Rendered as a nav landmark; give it an aria-label.
- Triggers announce expanded state and control their content.
- Full roving keyboard support from Radix.

Keyboard:

| Key | Action |
| --- | --- |
| Tab | Move to the next trigger or link. |
| Enter / Space | Open the focused trigger. |
| ArrowLeft / ArrowRight | Move between top level items. |
| ArrowDown | Enter open content. |
| Escape | Close content and return focus to trigger. |

ARIA:

- `aria-expanded` on triggers
- `aria-controls` links trigger to content
- `aria-current="page"` on active link

- Reduced motion: Panels fade and scale from 95% on open using transform and opacity only. With prefers-reduced-motion the animation is removed.

---

# Menubar

> Desktop-style horizontal menu bar with nested menus, checkbox and radio items.

- id: `menubar`
- type: primitive
- category: Navigation
- tags: primitive
- docs: https://glinui.com/docs/components/radix/menubar
- markdown: https://glinui.com/md/menubar.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add menubar
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/menubar.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Menubar, MenubarMenu, MenubarGroup, MenubarPortal, MenubarSub, MenubarRadioGroup, MenubarTrigger, MenubarContent } from "@glinui/ui"
```

## Usage

A code editor window with File open. Shortcuts sit at the end of each row and submenus nest with MenubarSub.

```tsx
"use client"

import * as React from "react"
import {
  Menubar,
  MenubarContent,
  MenubarItem,
  MenubarMenu,
  MenubarSeparator,
  MenubarShortcut,
  MenubarSub,
  MenubarSubContent,
  MenubarSubTrigger,
  MenubarTrigger
} from "@glinui/ui"

function EditorWindow({ open, children }: { open: "file" | "view"; children: React.ReactNode }) {
  return (
    <div className="mx-auto min-h-80 w-full max-w-2xl overflow-hidden rounded-xl border border-[var(--line-soft)] bg-[var(--surface-1)] [box-shadow:var(--elev-1)]">
      <div className="flex items-center gap-3 border-b border-[var(--line-soft)] px-2 py-1.5">
        <span className="ps-1 text-xs font-semibold" aria-hidden="true">{`{ }`}</span>
        <Menubar defaultValue={open} className="border-0 bg-transparent p-0 [box-shadow:none]">
          {children}
        </Menubar>
      </div>
      <div className="grid gap-1 p-4 font-mono text-xs leading-6 text-[var(--color-muted)]">
        <p><span className="text-[var(--color-accent)]">export</span> function Header() {"{"}</p>
        <p className="ps-4"><span className="text-[var(--color-accent)]">return</span> {"<nav aria-label=\"Main\" />"}</p>
        <p>{"}"}</p>
      </div>
    </div>
  )
}

export function MenubarEditorHero() {
  return (
    <EditorWindow open="file">
      <MenubarMenu value="file">
        <MenubarTrigger>File</MenubarTrigger>
        <MenubarContent className="w-60">
          <MenubarItem>New file <MenubarShortcut>Ctrl N</MenubarShortcut></MenubarItem>
          <MenubarItem>Open folder <MenubarShortcut>Ctrl O</MenubarShortcut></MenubarItem>
          <MenubarSub>
            <MenubarSubTrigger>Open recent</MenubarSubTrigger>
            <MenubarSubContent>
              <MenubarItem>lumen-web</MenubarItem>
              <MenubarItem>billing-service</MenubarItem>
            </MenubarSubContent>
          </MenubarSub>
          <MenubarSeparator />
          <MenubarItem>Save <MenubarShortcut>Ctrl S</MenubarShortcut></MenubarItem>
          <MenubarItem>Save all <MenubarShortcut>Ctrl Shift S</MenubarShortcut></MenubarItem>
          <MenubarSeparator />
          <MenubarItem>Close editor <MenubarShortcut>Ctrl W</MenubarShortcut></MenubarItem>
        </MenubarContent>
      </MenubarMenu>
      <MenubarMenu value="edit">
        <MenubarTrigger>Edit</MenubarTrigger>
        <MenubarContent className="w-56">
          <MenubarItem>Undo <MenubarShortcut>Ctrl Z</MenubarShortcut></MenubarItem>
          <MenubarItem>Redo <MenubarShortcut>Ctrl Y</MenubarShortcut></MenubarItem>
        </MenubarContent>
      </MenubarMenu>
      <MenubarMenu value="view">
        <MenubarTrigger>View</MenubarTrigger>
        <MenubarContent className="w-56">
          <MenubarItem>Command palette <MenubarShortcut>Ctrl K</MenubarShortcut></MenubarItem>
        </MenubarContent>
      </MenubarMenu>
    </EditorWindow>
  )
}
```

### View toggles

Checkbox and radio items for editor settings. Press the arrow keys to move between menus.

```tsx
"use client"

import * as React from "react"
import {
  Menubar,
  MenubarCheckboxItem,
  MenubarContent,
  MenubarItem,
  MenubarLabel,
  MenubarMenu,
  MenubarRadioGroup,
  MenubarRadioItem,
  MenubarSeparator,
  MenubarShortcut,
  MenubarTrigger
} from "@glinui/ui"

function EditorWindow({ open, children }: { open: "file" | "view"; children: React.ReactNode }) {
  return (
    <div className="mx-auto min-h-80 w-full max-w-2xl overflow-hidden rounded-xl border border-[var(--line-soft)] bg-[var(--surface-1)] [box-shadow:var(--elev-1)]">
      <div className="flex items-center gap-3 border-b border-[var(--line-soft)] px-2 py-1.5">
        <span className="ps-1 text-xs font-semibold" aria-hidden="true">{`{ }`}</span>
        <Menubar defaultValue={open} className="border-0 bg-transparent p-0 [box-shadow:none]">
          {children}
        </Menubar>
      </div>
      <div className="grid gap-1 p-4 font-mono text-xs leading-6 text-[var(--color-muted)]">
        <p><span className="text-[var(--color-accent)]">export</span> function Header() {"{"}</p>
        <p className="ps-4"><span className="text-[var(--color-accent)]">return</span> {"<nav aria-label=\"Main\" />"}</p>
        <p>{"}"}</p>
      </div>
    </div>
  )
}

export function MenubarViewExample() {
  const [minimap, setMinimap] = React.useState(true)
  const [wrap, setWrap] = React.useState(false)
  const [theme, setTheme] = React.useState("dark")
  return (
    <EditorWindow open="view">
      <MenubarMenu value="file">
        <MenubarTrigger>File</MenubarTrigger>
        <MenubarContent><MenubarItem>New file</MenubarItem></MenubarContent>
      </MenubarMenu>
      <MenubarMenu value="view">
        <MenubarTrigger>View</MenubarTrigger>
        <MenubarContent className="w-60">
          <MenubarLabel>Editor</MenubarLabel>
          <MenubarCheckboxItem checked={minimap} onCheckedChange={setMinimap}>Minimap</MenubarCheckboxItem>
          <MenubarCheckboxItem checked={wrap} onCheckedChange={setWrap}>Word wrap <MenubarShortcut>Alt Z</MenubarShortcut></MenubarCheckboxItem>
          <MenubarSeparator />
          <MenubarLabel>Color theme</MenubarLabel>
          <MenubarRadioGroup value={theme} onValueChange={setTheme}>
            <MenubarRadioItem value="light">Light</MenubarRadioItem>
            <MenubarRadioItem value="dark">Dark</MenubarRadioItem>
          </MenubarRadioGroup>
        </MenubarContent>
      </MenubarMenu>
    </EditorWindow>
  )
}
```

### Glass (opt-in)

Glass is opt-in and needs a colourful or photographic backdrop. Pick one in the stage header.

```tsx
import { Menubar, MenubarContent, MenubarItem, MenubarMenu, MenubarSeparator, MenubarShortcut, MenubarTrigger } from "@glinui/ui"

export function Demo() {
  return (
    <Menubar variant="glass">
      <MenubarMenu>
        <MenubarTrigger>File</MenubarTrigger>
        <MenubarContent>
          <MenubarItem>New tab <MenubarShortcut>Cmd T</MenubarShortcut></MenubarItem>
          <MenubarItem>New window</MenubarItem>
          <MenubarSeparator />
          <MenubarItem>Print</MenubarItem>
        </MenubarContent>
      </MenubarMenu>
      <MenubarMenu>
        <MenubarTrigger>Edit</MenubarTrigger>
        <MenubarContent>
          <MenubarItem>Undo</MenubarItem>
          <MenubarItem>Redo</MenubarItem>
        </MenubarContent>
      </MenubarMenu>
    </Menubar>
  )
}
```

## Props

### MenubarContentProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant?` | `MenubarVariant` |  | Surface look. Defaults to the bar's variant, then the ambient design style. |

### MenubarProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant?` | `MenubarVariant` |  | Surface look of the bar and its menus. Omit for the ambient design style (glinr by default). |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Uses the WAI-ARIA menubar pattern with roving focus.
- Check and radio items expose their checked state.
- Panels render in a portal and restore focus on close.

Keyboard:

| Key | Action |
| --- | --- |
| ArrowLeft / ArrowRight | Move between menu triggers. |
| ArrowDown | Open the menu and focus the first item. |
| ArrowUp / ArrowDown | Move between items. |
| Enter / Space | Select the focused item. |
| Escape | Close the menu. |

ARIA:

- `role="menubar"`, `menu`, `menuitem`
- `aria-checked` on checkbox and radio items
- `aria-haspopup` and `aria-expanded` on triggers

- Reduced motion: Panels fade and scale from 95% on open using transform and opacity only. With prefers-reduced-motion the animation is removed.

---

# Glass Navbar

> Translucent navigation bar that responds to scroll with blur intensity.

- id: `glass-navbar`
- type: signature
- category: Navigation
- tags: signature
- docs: https://glinui.com/docs/components/glass-navbar
- markdown: https://glinui.com/md/glass-navbar.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add glass-navbar
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/glass-navbar.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { GlassNavbar, PANEL_ITEM, PANEL_ITEM_SELECTABLE, PANEL_SEPARATOR, PANEL_MOTION, GLIN_MOTIONS, GLIN_ENGINES, GLIN_SURFACES } from "@glinui/ui"
```

## Usage

```tsx
import { GlassNavbar } from "@glinui/ui"

const variants = ["glinr", "plain", "solid", "soft", "outline", "ghost", "gradient", "glass"] as const

export function GlassNavbarVariantsDemo() {
  return (
    <div className="flex flex-col gap-3">
      {variants.map((variant) => (
        <GlassNavbar key={variant} variant={variant} disableScrollTracking className="rounded-xl px-4">
          <div className="flex h-12 items-center justify-between">
            <span className="text-sm font-semibold">{variant}</span>
            <span className="text-xs text-[var(--color-muted)]">Docs  Components  Changelog</span>
          </div>
        </GlassNavbar>
      ))}
    </div>
  )
}
```

```tsx
import { GlassNavbar } from "@glinui/ui"

export function GlassNavbarSizesDemo() {
  return (
    <div className="flex flex-col gap-4">
      <GlassNavbar size="sm" disableScrollTracking className="rounded-xl px-4">
        <div className="flex items-center justify-between">
          <span className="font-semibold text-sm">Small</span>
        </div>
      </GlassNavbar>
      <GlassNavbar size="md" disableScrollTracking className="rounded-xl px-4">
        <div className="flex items-center justify-between">
          <span className="font-semibold text-sm">Medium (default)</span>
        </div>
      </GlassNavbar>
      <GlassNavbar size="lg" disableScrollTracking className="rounded-xl px-4">
        <div className="flex items-center justify-between">
          <span className="font-semibold text-sm">Large</span>
        </div>
      </GlassNavbar>
    </div>
  )
}
```

```tsx
import { GlassNavbar } from "@glinui/ui"

export function GlassNavbarScrolledDemo() {
  return (
    <GlassNavbar elevation="scrolled" disableScrollTracking aria-label="Main navigation" className="rounded-xl px-6">
      <div className="flex h-14 items-center justify-between">
        <span className="font-semibold">Glin UI</span>
        <span className="text-sm text-neutral-600 dark:text-neutral-300">Scrolled elevation (forced)</span>
      </div>
    </GlassNavbar>
  )
}
```

## Props

### GlassNavbarProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disableScrollTracking?` | `boolean` | `false` |  |
| `elevation?` | `VariantProps<typeof glassNavbarVariants>["elevation"]` |  |  |
| `scrollThreshold?` | `number` | `8` |  |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from glassNavbarVariants. |
| `variant?` | `PanelVariantProp` |  | Surface look. The navbar is glass by default (its identity, with readable opacity floors so it stays legible on any backdrop). Pass `glin... |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Renders as a semantic `` element, add `aria-label` (e.g. `"Main navigation"`) to distinguish multiple navbars on the page.
- Child links and buttons retain native keyboard navigation with no custom focus management applied.
- Reduced motion: The blur and opacity transition between `base` and `scrolled` elevation states is disabled when `prefers-reduced-motion` is active.

---

# Glass Dock

> macOS-style dock with proximity magnification and frosted glass surface.

- id: `glass-dock`
- type: signature
- category: Navigation
- tags: signature
- docs: https://glinui.com/docs/components/glass-dock
- markdown: https://glinui.com/md/glass-dock.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add glass-dock
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/glass-dock.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { GlassDock, PANEL_ITEM, PANEL_ITEM_SELECTABLE, PANEL_SEPARATOR, PANEL_MOTION, SURFACE_VARIANTS, SURFACE_TONES, SURFACE_ELEVATIONS } from "@glinui/ui"
```

## Usage

```tsx
"use client"
import { GlassDock } from "@glinui/ui"
import { House, Gear, User } from "@phosphor-icons/react"

const variants = ["glinr", "plain", "solid", "soft", "outline", "ghost", "gradient", "glass"] as const

export function GlassDockVariantsDemo() {
  const items = [
    { id: "home", icon: <House className="size-full" />, label: "Home" },
    { id: "settings", icon: <Gear className="size-full" />, label: "Settings" },
    { id: "profile", icon: <User className="size-full" />, label: "Profile" }
  ]
  return (
    <div className="grid gap-4 sm:grid-cols-2">
      {variants.map((variant) => (
        <GlassDock key={variant} variant={variant} iconSize={40} items={items} />
      ))}
    </div>
  )
}
```

```tsx
"use client"
import { GlassDock } from "@glinui/ui"
import { FolderOpen, Camera, MusicNote, FilmStrip, Globe, ChatCircle } from "@phosphor-icons/react"

export function GlassDockMagDemo() {
  return (
    <div className="flex items-center justify-center p-12">
      <GlassDock
        magnification={2}
        distance={150}
        iconSize={56}
        items={[
          { id: "files", icon: <FolderOpen className="size-full" />, label: "Files" },
          { id: "photos", icon: <Camera className="size-full" />, label: "Photos" },
          { id: "music", icon: <MusicNote className="size-full" />, label: "Music" },
          { id: "video", icon: <FilmStrip className="size-full" />, label: "Video" },
          { id: "web", icon: <Globe className="size-full" />, label: "Browser" },
          { id: "messages", icon: <ChatCircle className="size-full" />, label: "Messages" }
        ]}
      />
    </div>
  )
}
```

## Props

### GlassDockProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `distance?` | `number` | `120` | Distance in px at which magnification starts |
| `iconSize?` | `number` | `48` | Base icon size in px |
| `items` | `GlassDockItem[]` |  | Dock items |
| `magnification?` | `number` | `1.6` | Maximum magnification scale |
| `position?` | `"bottom" \| "top" \| "left" \| "right"` | `"bottom"` | Position |
| `variant?` | `PanelVariantProp` |  | Surface look. Glass by default (its identity, with a readable opacity floor). Pass `glinr`, `plain`, `solid`, `soft`, `outline`, `ghost` ... |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Renders with `role="toolbar"` and `aria-label="Dock"`.
- Each item is a `` with `aria-label` set to the item label.
- Item tooltips appear on hover using the `title` attribute.
- Reduced motion: When `prefers-reduced-motion: reduce` is active, the magnification effect is disabled, all items remain at their base size.

---

# Tabs

> Tabbed interface for switching between grouped content panels.

- id: `tabs`
- type: primitive
- category: Navigation
- tags: primitive
- docs: https://glinui.com/docs/components/radix/tabs
- markdown: https://glinui.com/md/tabs.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add tabs
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/tabs.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Tabs, TabsList, TabsTrigger, TabsContent, CONTROL_LEGACY_VARIANTS, CONTROL_SIZE_CLASSES, GlinProvider, GLIN_MOTIONS } from "@glinui/ui"
```

## Usage

Tabs above a real panel: the active tab swaps the content, and arrow keys move focus between triggers.

```tsx
"use client"

import {
  Avatar,
  Badge,
  Heading,
  Tabs,
  TabsContent,
  TabsList,
  TabsTrigger,
  Text
} from "@glinui/ui"

const ACTIVITY = [
  { who: "AK", text: "Ava Kim merged release 2.4 into main", when: "12 min ago" },
  { who: "JR", text: "Jon Reyes commented on the pricing page", when: "1 h ago" },
  { who: "SP", text: "Sara Patel invited two teammates", when: "Yesterday" }
]

export function TabsProjectHero() {
  return (
    <div className="mx-auto w-full max-w-xl rounded-2xl border border-[var(--line-soft)] bg-[var(--surface-1)] p-5 [box-shadow:var(--elev-1)]">
      <div className="flex items-center justify-between gap-3">
        <div>
          <Heading level={3} size="sm">Lumen web app</Heading>
          <Text size="sm" className="text-[var(--color-muted)]">Production, deployed 12 minutes ago</Text>
        </div>
        <Badge tone="success" dot>Live</Badge>
      </div>
      <Tabs defaultValue="activity" className="mt-4">
        <TabsList>
          <TabsTrigger value="overview">Overview</TabsTrigger>
          <TabsTrigger value="activity">Activity</TabsTrigger>
          <TabsTrigger value="billing">Billing</TabsTrigger>
        </TabsList>
        <TabsContent value="overview">
          <Text size="sm" className="pt-3 text-[var(--color-muted)]">48.2k visits this week, up 12% on last week.</Text>
        </TabsContent>
        <TabsContent value="activity">
          <ul className="grid gap-3 pt-3">
            {ACTIVITY.map((row) => (
              <li key={row.text} className="flex items-center gap-3">
                <Avatar size="sm" fallback={row.who} alt="" />
                <span className="grid text-sm">
                  <span>{row.text}</span>
                  <span className="text-xs text-[var(--color-muted)]">{row.when}</span>
                </span>
              </li>
            ))}
          </ul>
        </TabsContent>
        <TabsContent value="billing">
          <Text size="sm" className="pt-3 text-[var(--color-muted)]">Team plan, renews on 1 November. Next invoice: $240.00.</Text>
        </TabsContent>
      </Tabs>
    </div>
  )
}
```

### Underline with icons

The underline look with icons, a count badge and a disabled tab.

```tsx
"use client"

import { Receipt, ShieldCheck, UsersThree } from "@phosphor-icons/react"
import {
  Badge,
  Tabs,
  TabsContent,
  TabsList,
  TabsTrigger,
  Text
} from "@glinui/ui"

export function TabsUnderlineExample() {
  return (
    <div className="mx-auto w-full max-w-xl">
      <Tabs defaultValue="members">
        <TabsList variant="underline" className="w-full justify-start overflow-x-auto">
          <TabsTrigger value="members" className="gap-1.5"><UsersThree aria-hidden="true" />Members</TabsTrigger>
          <TabsTrigger value="roles" className="gap-1.5"><ShieldCheck aria-hidden="true" />Roles</TabsTrigger>
          <TabsTrigger value="invoices" className="gap-1.5"><Receipt aria-hidden="true" />Invoices <Badge size="sm">3</Badge></TabsTrigger>
          <TabsTrigger value="locked" disabled>Audit log</TabsTrigger>
        </TabsList>
        <TabsContent value="members"><Text size="sm" className="pt-4 text-[var(--color-muted)]">12 members across 3 teams.</Text></TabsContent>
        <TabsContent value="roles"><Text size="sm" className="pt-4 text-[var(--color-muted)]">Owner, admin, editor and viewer roles.</Text></TabsContent>
        <TabsContent value="invoices"><Text size="sm" className="pt-4 text-[var(--color-muted)]">3 invoices are waiting for payment.</Text></TabsContent>
      </Tabs>
    </div>
  )
}
```

### Variants

Set variant once on Tabs and the list, triggers and panels inherit it. glinr is the raised pill track, underline slides an accent bar with transform only.

```tsx
import { Tabs, TabsList, TabsTrigger } from "@glinui/ui"

export function Demo() {
  return (
    <div className="grid gap-4 md:grid-cols-2">
      <Tabs defaultValue="a" variant="glinr">
        <TabsList>
          <TabsTrigger value="a">glinr</TabsTrigger>
          <TabsTrigger value="b">Two</TabsTrigger>
          <TabsTrigger value="c">Three</TabsTrigger>
        </TabsList>
      </Tabs>
      <Tabs defaultValue="a" variant="solid">
        <TabsList>
          <TabsTrigger value="a">solid</TabsTrigger>
          <TabsTrigger value="b">Two</TabsTrigger>
          <TabsTrigger value="c">Three</TabsTrigger>
        </TabsList>
      </Tabs>
      <Tabs defaultValue="a" variant="plain">
        <TabsList>
          <TabsTrigger value="a">plain</TabsTrigger>
          <TabsTrigger value="b">Two</TabsTrigger>
          <TabsTrigger value="c">Three</TabsTrigger>
        </TabsList>
      </Tabs>
      <Tabs defaultValue="a" variant="soft">
        <TabsList>
          <TabsTrigger value="a">soft</TabsTrigger>
          <TabsTrigger value="b">Two</TabsTrigger>
          <TabsTrigger value="c">Three</TabsTrigger>
        </TabsList>
      </Tabs>
      <Tabs defaultValue="a" variant="outline">
        <TabsList>
          <TabsTrigger value="a">outline</TabsTrigger>
          <TabsTrigger value="b">Two</TabsTrigger>
          <TabsTrigger value="c">Three</TabsTrigger>
        </TabsList>
      </Tabs>
      <Tabs defaultValue="a" variant="underline">
        <TabsList>
          <TabsTrigger value="a">underline</TabsTrigger>
          <TabsTrigger value="b">Two</TabsTrigger>
          <TabsTrigger value="c">Three</TabsTrigger>
        </TabsList>
      </Tabs>
    </div>
  )
}
```

## Props

### TabsContentProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size?` | `TabsSize` |  |  |
| `variant?` | `TabsVariant` |  |  |

### TabsListProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size?` | `TabsSize` |  |  |
| `variant?` | `TabsVariant` |  |  |

### TabsProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size?` | `TabsSize` |  | Default size for every part inside. |
| `variant?` | `TabsVariant` |  | Default look for every list, trigger and panel inside. Each part can still set its own. |

### TabsTriggerProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size?` | `TabsSize` |  |  |
| `variant?` | `TabsVariant` |  |  |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Built on Radix Tabs with full WAI-ARIA.
- Content is associated via `aria-controls`.
- Use clear trigger labels for each panel.

Keyboard:

| Key | Action |
| --- | --- |
| Arrow Left / Right | Navigate between tab triggers. |
| Enter / Space | Select the focused tab. |

ARIA:

- `role="tablist"` on list
- `role="tab"` on triggers
- `role="tabpanel"` on content
- `aria-selected`
- `aria-controls`

- Reduced motion: Active indicator transitions respect `prefers-reduced-motion`. Tabs do not require motion for state communication.

---

# Morphing Tabs

> Tab component with a smoothly sliding indicator that morphs between items.

- id: `morphing-tabs`
- type: signature
- category: Navigation
- tags: signature
- docs: https://glinui.com/docs/components/morphing-tabs
- markdown: https://glinui.com/md/morphing-tabs.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add morphing-tabs
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/morphing-tabs.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { MorphingTabs, CONTROL_LEGACY_VARIANTS, CONTROL_SIZE_CLASSES, GlinProvider, GLIN_MOTIONS, GLIN_ENGINES, GLIN_SURFACES, GLIN_STYLES } from "@glinui/ui"
```

## Usage

```tsx
"use client"
import { MorphingTabs } from "@glinui/ui"

export function MorphingTabsUnderlineDemo() {
  return (
    <div className="flex items-center justify-center p-8">
      <MorphingTabs
        variant="underline"
        items={[
          { id: "all", label: "All" },
          { id: "active", label: "Active" },
          { id: "archived", label: "Archived" }
        ]}
      />
    </div>
  )
}
```

```tsx
"use client"
import { MorphingTabs } from "@glinui/ui"

export function MorphingTabsSolidDemo() {
  return (
    <div className="flex items-center justify-center p-8">
      <MorphingTabs
        variant="solid"
        size="lg"
        items={[
          { id: "daily", label: "Daily" },
          { id: "weekly", label: "Weekly" },
          { id: "monthly", label: "Monthly" }
        ]}
      />
    </div>
  )
}
```

```tsx
"use client"
import { MorphingTabs } from "@glinui/ui"

export function MorphingTabsVariantsDemo() {
  return (
    <div className="flex flex-col items-start gap-4">
      <MorphingTabs variant="glinr" items={[
          { id: "a", label: "One" },
          { id: "b", label: "Two" },
          { id: "c", label: "Three" }
        ]} />
      <MorphingTabs variant="plain" items={[
          { id: "a", label: "One" },
          { id: "b", label: "Two" },
          { id: "c", label: "Three" }
        ]} />
      <MorphingTabs variant="soft" items={[
          { id: "a", label: "One" },
          { id: "b", label: "Two" },
          { id: "c", label: "Three" }
        ]} />
      <MorphingTabs variant="outline" items={[
          { id: "a", label: "One" },
          { id: "b", label: "Two" },
          { id: "c", label: "Three" }
        ]} />
      <MorphingTabs variant="ghost" items={[
          { id: "a", label: "One" },
          { id: "b", label: "Two" },
          { id: "c", label: "Three" }
        ]} />
    </div>
  )
}
```

## Props

### MorphingTabsProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `activeId?` | `string` |  | Active tab id |
| `defaultActiveId?` | `string` |  | Default active tab id |
| `items` | `MorphingTabItem[]` |  | Tab items |
| `onTabChange?` | `(id: string) => void` |  | Callback when active tab changes |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Size |
| `variant?` | `ControlVariantProp` |  | Look. Omit to follow the ambient design style (glinr = raised pill track with a sliding key). Also: solid, plain, soft, outline, ghost, u... |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Renders with `role="tablist"` on the container and `role="tab"` on each button.
- `aria-selected` is set on the active tab.
- Disabled tabs receive `disabled` attribute and are visually marked.
- Reduced motion: When `prefers-reduced-motion: reduce` is active, the indicator transition duration is set to `0` for instant position changes.

---

# Breadcrumb

> Navigation trail with separators, collapsed ellipsis and variant-capable links.

- id: `breadcrumb`
- type: primitive
- category: Navigation
- tags: primitive
- docs: https://glinui.com/docs/components/radix/breadcrumb
- markdown: https://glinui.com/md/breadcrumb.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add breadcrumb
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/breadcrumb.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Breadcrumb, BreadcrumbList, BreadcrumbItem, BreadcrumbLink, BreadcrumbPage, BreadcrumbSeparator, BreadcrumbEllipsis, LIFT_RING } from "@glinui/ui"
```

## Usage

A trail with a home icon, a collapsed middle segment and the current page, above the page title and action.

```tsx
"use client"

import { House } from "@phosphor-icons/react"
import {
  Breadcrumb,
  BreadcrumbEllipsis,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbPage,
  BreadcrumbSeparator,
  Button,
  Heading,
  Text
} from "@glinui/ui"

export function BreadcrumbHeaderHero() {
  return (
    <div className="mx-auto w-full max-w-2xl rounded-2xl border border-[var(--line-soft)] bg-[var(--surface-1)] p-5 [box-shadow:var(--elev-1)]">
      <Breadcrumb>
        <BreadcrumbList>
          <BreadcrumbItem><BreadcrumbLink href="#"><House aria-hidden="true" className="size-4" /><span className="sr-only">Home</span></BreadcrumbLink></BreadcrumbItem>
          <BreadcrumbSeparator />
          <BreadcrumbItem><BreadcrumbEllipsis /></BreadcrumbItem>
          <BreadcrumbSeparator />
          <BreadcrumbItem><BreadcrumbLink href="#">Projects</BreadcrumbLink></BreadcrumbItem>
          <BreadcrumbSeparator />
          <BreadcrumbItem><BreadcrumbLink href="#">Lumen web</BreadcrumbLink></BreadcrumbItem>
          <BreadcrumbSeparator />
          <BreadcrumbItem><BreadcrumbPage>Deployments</BreadcrumbPage></BreadcrumbItem>
        </BreadcrumbList>
      </Breadcrumb>
      <div className="mt-4 flex flex-wrap items-center justify-between gap-3">
        <div>
          <Heading level={3} size="md">Deployments</Heading>
          <Text size="sm" className="text-[var(--color-muted)]">Every build of Lumen web, newest first.</Text>
        </div>
        <Button size="sm">New deployment</Button>
      </div>
    </div>
  )
}
```

### Separators

Pass any node as the separator, and keep the current page as plain text with BreadcrumbPage.

```tsx
"use client"

import { FileText } from "@phosphor-icons/react"
import {
  Breadcrumb,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbPage,
  BreadcrumbSeparator
} from "@glinui/ui"

export function BreadcrumbFilesExample() {
  return (
    <div className="mx-auto grid w-full max-w-xl gap-4">
      <Breadcrumb>
        <BreadcrumbList>
          <BreadcrumbItem><BreadcrumbLink href="#">Documents</BreadcrumbLink></BreadcrumbItem>
          <BreadcrumbSeparator>/</BreadcrumbSeparator>
          <BreadcrumbItem><BreadcrumbLink href="#">Contracts</BreadcrumbLink></BreadcrumbItem>
          <BreadcrumbSeparator>/</BreadcrumbSeparator>
          <BreadcrumbItem><BreadcrumbPage><FileText aria-hidden="true" className="me-1 inline size-4" />Vendor agreement.pdf</BreadcrumbPage></BreadcrumbItem>
        </BreadcrumbList>
      </Breadcrumb>
      <Breadcrumb>
        <BreadcrumbList>
          <BreadcrumbItem><BreadcrumbLink href="#">Settings</BreadcrumbLink></BreadcrumbItem>
          <BreadcrumbSeparator />
          <BreadcrumbItem><BreadcrumbPage>Billing</BreadcrumbPage></BreadcrumbItem>
        </BreadcrumbList>
      </Breadcrumb>
    </div>
  )
}
```

### Glass (opt-in)

Glass is opt-in and needs a colourful or photographic backdrop to read as frosted. Pick one in the stage header.

```tsx
import { Breadcrumb, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator } from "@glinui/ui"

export function Demo() {
  return (
    <Breadcrumb variant="glass">
      <BreadcrumbList>
        <BreadcrumbItem><BreadcrumbLink href="/">Home</BreadcrumbLink></BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem><BreadcrumbEllipsis /></BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem><BreadcrumbPage>Settings</BreadcrumbPage></BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  )
}
```

## Props

### BreadcrumbLinkProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `asChild?` | `boolean` |  |  |

### BreadcrumbProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant?` | `PanelVariantProp` |  | Surface look. Omit for the ambient design style (glinr by default): a bare trail whose current page is a raised pill. `solid`, `soft`, `o... |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Rendered as a nav landmark labelled breadcrumb with an ordered list.
- The current page is marked with aria-current=page.
- Separators are hidden from assistive tech; the ellipsis exposes a screen reader label.

Keyboard:

| Key | Action |
| --- | --- |
| Tab | Move through breadcrumb links in order. |

ARIA:

- `aria-label="breadcrumb"` on nav
- `aria-current="page"` on BreadcrumbPage
- `aria-hidden` on separators

- Reduced motion: Only color transitions are used, and they are disabled with prefers-reduced-motion.

---

# Glass Breadcrumb

> Pill-style breadcrumb with glass indicators and collapsible items.

- id: `glass-breadcrumb`
- type: signature
- category: Navigation
- tags: signature
- docs: https://glinui.com/docs/components/glass-breadcrumb
- markdown: https://glinui.com/md/glass-breadcrumb.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add glass-breadcrumb
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/glass-breadcrumb.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { GlassBreadcrumb, PANEL_ITEM, PANEL_ITEM_SELECTABLE, PANEL_SEPARATOR, PANEL_MOTION, GLIN_MOTIONS, GLIN_ENGINES, GLIN_SURFACES } from "@glinui/ui"
```

## Usage

```tsx
import { GlassBreadcrumb } from "@glinui/ui"

const variants = ["glinr", "plain", "solid", "soft", "outline", "ghost", "gradient", "glass"] as const

export function GlassBreadcrumbVariantsDemo() {
  const items = [
    { id: "home", label: "Home", href: "/" },
    { id: "docs", label: "Docs", href: "/docs" },
    { id: "breadcrumb", label: "Breadcrumb" }
  ]
  return (
    <div className="flex flex-col items-start gap-3">
      {variants.map((variant) => (
        <GlassBreadcrumb key={variant} variant={variant} items={items} />
      ))}
    </div>
  )
}
```

```tsx
import { GlassBreadcrumb } from "@glinui/ui"

export function GlassBreadcrumbCollapsedDemo() {
  return (
    <div className="flex items-center justify-center p-8">
      <GlassBreadcrumb
        maxItems={3}
        items={[
          { id: "home", label: "Home", href: "/" },
          { id: "docs", label: "Docs", href: "/docs" },
          { id: "components", label: "Components", href: "/docs/components" },
          { id: "signature", label: "Signature", href: "/docs/components" },
          { id: "breadcrumb", label: "Breadcrumb" }
        ]}
      />
    </div>
  )
}
```

## Props

### GlassBreadcrumbProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `GlassBreadcrumbItem[]` |  | Breadcrumb items |
| `maxItems?` | `number` |  | Max items to show (rest collapsed) |
| `separator?` | `React.ReactNode` | `"/"` | Separator character |
| `variant?` | `PanelVariantProp` |  | Surface look. Glass by default (its identity, with a readable opacity floor). Pass `glinr`, `plain`, `solid`, `soft`, `outline`, `ghost` ... |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Renders as `` with an `` list.
- The current page has `aria-current="page"`.
- Separators are `aria-hidden`.
- Reduced motion: No animations, the component is fully static.

---

# Sidebar

> Collapsible app sidebar with icon rail, mobile sheet, Ctrl/Cmd+B shortcut, and persisted state.

- id: `sidebar`
- type: primitive
- category: Navigation
- tags: primitive
- docs: https://glinui.com/docs/components/radix/sidebar
- markdown: https://glinui.com/md/sidebar.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add sidebar
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/sidebar.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Sidebar, SidebarTrigger, SidebarRail, SidebarInset, SidebarHeader, SidebarFooter, SidebarSeparator, SidebarContent } from "@glinui/ui"
```

## Usage

The sidebar animates its width when it collapses. Width is a documented exception to the transform and opacity only motion rule, because the content column must reflow with it. The transition is disabled under prefers-reduced-motion.

Use containerClassName to control the docking element, for example static h-full when the sidebar lives inside a bounded frame instead of the viewport.

Every look of the shared vocabulary. glinr (the default) is a lifted rail with hairline separators and a raised pill for the active item; plain is flat and shadcn-like. Collapsed icon mode keeps the same pill as a circle.

```tsx
import { Sidebar, SidebarContent, SidebarGroup, SidebarGroupContent, SidebarGroupLabel, SidebarHeader, SidebarMenu, SidebarMenuButton, SidebarMenuItem, SidebarProvider } from "@glinui/ui"

const variants = ["glinr", "plain", "solid", "soft", "outline", "ghost", "gradient", "glass"] as const

export function Demo() {
  return variants.map((variant) => (
    <SidebarProvider key={variant}>
      <Sidebar variant={variant} collapsible="none">
        <SidebarHeader>{variant}</SidebarHeader>
        <SidebarContent>
          <SidebarGroup>
            <SidebarGroupLabel>Platform</SidebarGroupLabel>
            <SidebarGroupContent>
              <SidebarMenu>
                <SidebarMenuItem><SidebarMenuButton isActive>Home</SidebarMenuButton></SidebarMenuItem>
                <SidebarMenuItem><SidebarMenuButton>Inbox</SidebarMenuButton></SidebarMenuItem>
              </SidebarMenu>
            </SidebarGroupContent>
          </SidebarGroup>
        </SidebarContent>
      </Sidebar>
    </SidebarProvider>
  ))
}
```

### Glass (opt-in)

Glass is opt-in and needs a colourful or photographic backdrop behind the rail. The frame supplies one here.

```tsx
import {
  Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupContent,
  SidebarGroupLabel, SidebarHeader, SidebarInset, SidebarMenu, SidebarMenuButton,
  SidebarMenuItem, SidebarProvider, SidebarRail, SidebarTrigger
} from "@glinui/ui"
import { House, Gear } from "@phosphor-icons/react"

export function Layout({ children }: { children: React.ReactNode }) {
  return (
    <SidebarProvider>
      <Sidebar variant="glass" collapsible="icon">
        <SidebarHeader>Glin Studio</SidebarHeader>
        <SidebarContent>
          <SidebarGroup>
            <SidebarGroupLabel>Platform</SidebarGroupLabel>
            <SidebarGroupContent>
              <SidebarMenu>
                <SidebarMenuItem>
                  <SidebarMenuButton isActive tooltip="Home"><House /><span>Home</span></SidebarMenuButton>
                </SidebarMenuItem>
                <SidebarMenuItem>
                  <SidebarMenuButton tooltip="Settings"><Gear /><span>Settings</span></SidebarMenuButton>
                </SidebarMenuItem>
              </SidebarMenu>
            </SidebarGroupContent>
          </SidebarGroup>
        </SidebarContent>
        <SidebarFooter>Footer</SidebarFooter>
        <SidebarRail />
      </Sidebar>
      <SidebarInset>
        <SidebarTrigger />
        {children}
      </SidebarInset>
    </SidebarProvider>
  )
}
```

### Off-canvas

Collapses fully; reopen with the trigger.

```tsx
import {
  Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupContent,
  SidebarGroupLabel, SidebarHeader, SidebarInset, SidebarMenu, SidebarMenuButton,
  SidebarMenuItem, SidebarProvider, SidebarRail, SidebarTrigger
} from "@glinui/ui"
import { House, Gear } from "@phosphor-icons/react"

export function Layout({ children }: { children: React.ReactNode }) {
  return (
    <SidebarProvider>
      <Sidebar collapsible="offcanvas">
        <SidebarHeader>Glin Studio</SidebarHeader>
        <SidebarContent>
          <SidebarGroup>
            <SidebarGroupLabel>Platform</SidebarGroupLabel>
            <SidebarGroupContent>
              <SidebarMenu>
                <SidebarMenuItem>
                  <SidebarMenuButton isActive tooltip="Home"><House /><span>Home</span></SidebarMenuButton>
                </SidebarMenuItem>
                <SidebarMenuItem>
                  <SidebarMenuButton tooltip="Settings"><Gear /><span>Settings</span></SidebarMenuButton>
                </SidebarMenuItem>
              </SidebarMenu>
            </SidebarGroupContent>
          </SidebarGroup>
        </SidebarContent>
        <SidebarFooter>Footer</SidebarFooter>
        <SidebarRail />
      </Sidebar>
      <SidebarInset>
        <SidebarTrigger />
        {children}
      </SidebarInset>
    </SidebarProvider>
  )
}
```

## Props

### SidebarGroupProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `collapsible?` | `boolean` | `false` | Let users collapse this group by activating its label. |
| `defaultOpen?` | `boolean` | `true` | Initial open state for a collapsible group. |

### SidebarMenuButtonProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `asChild?` | `boolean` | `false` |  |
| `isActive?` | `boolean` | `false` | Marks the current page. Sets aria-current="page". |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from menuButtonVariants. |
| `tooltip?` | `string` |  | Tooltip shown only while the sidebar is collapsed to icons. |
| `variant?` | `"default" \| "outline"` | `"default"` | Variant option from menuButtonVariants. |

### SidebarProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `collapsible?` | `"offcanvas" \| "icon" \| "none"` | `false` | How the sidebar collapses on desktop. |
| `containerClassName?` | `string` |  | Class names for the outer docking element (height, position). Defaults to sticky full viewport height. |
| `label?` | `string` | `"Sidebar"` | Accessible name for the navigation landmark. |
| `side?` | `"start" \| "end"` | `"start"` | Which inline edge the sidebar docks to. |
| `variant?` | `PanelVariantProp` |  | Surface look. Omit for the ambient design style (glinr by default): a lifted rail with hairline separators and a raised pill for the acti... |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`, `outline`.

## Accessibility

- The panel is a `nav` landmark with an accessible name.
- The current page uses `aria-current="page"`; collapsible group labels expose `aria-expanded` and `aria-controls`.
- On small screens the sidebar becomes a Sheet dialog with focus trap and Escape to close.
- In icon mode, labels stay in the accessibility tree (visually hidden) and tooltips reveal them.

Keyboard:

| Key | Action |
| --- | --- |
| Ctrl/Cmd + B | Toggle the sidebar. |
| Tab / Shift + Tab | Move through menu buttons. |
| Enter / Space | Activate a button or toggle a group. |
| Escape | Close the mobile sheet. |

ARIA:

- `<nav aria-label>`
- `aria-current="page"` on the active button
- `aria-expanded` on trigger and collapsible group labels

- Reduced motion: Width and caret transitions are disabled; state changes apply instantly.

---

# Pagination

> Page navigation with previous and next controls, numbered links and ellipsis.

- id: `pagination`
- type: primitive
- category: Navigation
- tags: primitive
- docs: https://glinui.com/docs/components/radix/pagination
- markdown: https://glinui.com/md/pagination.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add pagination
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/pagination.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Pagination, PaginationContent, PaginationItem, PaginationLink, PaginationPrevious, PaginationNext, PaginationEllipsis, PanelVariantProvider } from "@glinui/ui"
```

## Usage

Page links below an invoices table, with a range summary on the left.

```tsx
"use client"

import {
  Badge,
  Pagination,
  PaginationContent,
  PaginationEllipsis,
  PaginationItem,
  PaginationLink,
  PaginationNext,
  PaginationPrevious,
  Table,
  TableBody,
  TableCell,
  TableHead,
  TableHeader,
  TableRow,
  Text
} from "@glinui/ui"

const INVOICES = [
  { id: "INV-1042", customer: "Northwind Traders", amount: "$1,280.00", status: "Paid", tone: "success" },
  { id: "INV-1041", customer: "Halcyon Labs", amount: "$640.00", status: "Pending", tone: "warning" },
  { id: "INV-1040", customer: "Brightside Co", amount: "$2,150.00", status: "Paid", tone: "success" },
  { id: "INV-1039", customer: "Orbit Studio", amount: "$320.00", status: "Overdue", tone: "danger" }
] as const

export function PaginationTableHero() {
  return (
    <div className="mx-auto w-full max-w-2xl rounded-2xl border border-[var(--line-soft)] bg-[var(--surface-1)] p-4 [box-shadow:var(--elev-1)]">
      <div className="overflow-x-auto">
        <Table>
          <TableHeader>
            <TableRow>
              <TableHead>Invoice</TableHead>
              <TableHead>Customer</TableHead>
              <TableHead>Status</TableHead>
              <TableHead className="text-end">Amount</TableHead>
            </TableRow>
          </TableHeader>
          <TableBody>
            {INVOICES.map((row) => (
              <TableRow key={row.id}>
                <TableCell className="font-medium">{row.id}</TableCell>
                <TableCell>{row.customer}</TableCell>
                <TableCell><Badge size="sm" tone={row.tone} dot>{row.status}</Badge></TableCell>
                <TableCell className="text-end tabular-nums">{row.amount}</TableCell>
              </TableRow>
            ))}
          </TableBody>
        </Table>
      </div>
      <div className="mt-4 flex flex-wrap items-center justify-between gap-3">
        <Text size="sm" className="text-[var(--color-muted)]">Showing 1 to 4 of 48 invoices</Text>
        <Pagination className="mx-0 w-auto">
          <PaginationContent>
            <PaginationItem><PaginationPrevious href="#" /></PaginationItem>
            <PaginationItem><PaginationLink href="#" isActive>1</PaginationLink></PaginationItem>
            <PaginationItem><PaginationLink href="#">2</PaginationLink></PaginationItem>
            <PaginationItem><PaginationLink href="#">3</PaginationLink></PaginationItem>
            <PaginationItem><PaginationEllipsis /></PaginationItem>
            <PaginationItem><PaginationLink href="#">12</PaginationLink></PaginationItem>
            <PaginationItem><PaginationNext href="#" /></PaginationItem>
          </PaginationContent>
        </Pagination>
      </div>
    </div>
  )
}
```

### Compact

Drop the ellipsis and numbered range when there are only a few pages.

```tsx
"use client"

import {
  Pagination,
  PaginationContent,
  PaginationItem,
  PaginationLink,
  PaginationNext,
  PaginationPrevious
} from "@glinui/ui"

export function PaginationCompactExample() {
  return (
    <div className="mx-auto grid w-full max-w-md gap-6">
      <Pagination>
        <PaginationContent>
          <PaginationItem><PaginationPrevious href="#" /></PaginationItem>
          <PaginationItem><PaginationLink href="#" isActive>4</PaginationLink></PaginationItem>
          <PaginationItem><PaginationNext href="#" /></PaginationItem>
        </PaginationContent>
      </Pagination>
      <Pagination>
        <PaginationContent>
          <PaginationItem><PaginationLink href="#" aria-label="Page 1">1</PaginationLink></PaginationItem>
          <PaginationItem><PaginationLink href="#" isActive aria-label="Page 2">2</PaginationLink></PaginationItem>
          <PaginationItem><PaginationLink href="#" aria-label="Page 3">3</PaginationLink></PaginationItem>
        </PaginationContent>
      </Pagination>
    </div>
  )
}
```

### Glass (opt-in)

Glass is opt-in and needs a colourful or photographic backdrop to read as frosted. Pick one in the stage header.

```tsx
import { Pagination, PaginationContent, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious } from "@glinui/ui"

export function Demo() {
  return (
    <Pagination variant="glass">
      <PaginationContent>
        <PaginationItem><PaginationPrevious href="#" /></PaginationItem>
        <PaginationItem><PaginationLink href="#">1</PaginationLink></PaginationItem>
        <PaginationItem><PaginationLink href="#" isActive>2</PaginationLink></PaginationItem>
        <PaginationItem><PaginationNext href="#" /></PaginationItem>
      </PaginationContent>
    </Pagination>
  )
}
```

## Props

### PaginationLinkProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `isActive?` | `boolean` |  |  |
| `size?` | `NonNullable<VariantProps<typeof paginationLinkVariants>["size"]>` | `"icon"` |  |

### PaginationProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant?` | `PanelVariantProp` |  | Look of the page links. Omit for the ambient design style (glinr by default): pill links with a raised current page. `plain` is the shadc... |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Rendered as a nav landmark labelled pagination.
- The active page link carries aria-current=page.
- Previous and next have explicit accessible names; the ellipsis has a screen reader label.

Keyboard:

| Key | Action |
| --- | --- |
| Tab | Move through page links. |
| Enter | Follow the focused link. |

ARIA:

- `aria-label="pagination"` on nav
- `aria-current="page"` on active link
- `aria-label="Go to next page"`

- Reduced motion: Only color transitions are used, and they are disabled with prefers-reduced-motion.

---

# Link

> Tokenized anchor primitive with focus ring and variant surfaces.

- id: `link`
- type: primitive
- category: Navigation
- tags: primitive
- docs: https://glinui.com/docs/components/radix/link
- markdown: https://glinui.com/md/link.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add link
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/link.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Link } from "@glinui/ui"
```

## Usage

Inline, arrow and footer links in one card.

```tsx
"use client"

import {
  Badge,
  Heading,
  Link,
  Text
} from "@glinui/ui"

export function LinkChangelogHero() {
  return (
    <div className="mx-auto w-full max-w-md rounded-2xl border border-[var(--line-soft)] bg-[var(--surface-1)] p-5 [box-shadow:var(--elev-1)]">
      <div className="flex items-center gap-2">
        <Badge tone="accent" size="sm">v2.4</Badge>
        <Text size="sm" className="text-[var(--color-muted)]">Released 3 October</Text>
      </div>
      <Heading level={3} size="md" className="mt-3">Faster dashboards</Heading>
      <Text className="mt-2 text-[var(--color-muted)]">
        Charts now render from cached queries, so the overview loads in under a second. Read the{" "}
        <Link href="#">migration notes</Link> before upgrading, or check the <Link href="#" underline={false}>full changelog</Link>.
      </Text>
      <div className="mt-4 flex flex-wrap items-center gap-4">
        <Link href="#" variant="arrow">Read the release post</Link>
        <Link href="#" variant="ghost">Download notes</Link>
      </div>
      <nav aria-label="Footer" className="mt-5 flex flex-wrap gap-x-4 gap-y-1 border-t border-[var(--line-soft)] pt-3 text-sm">
        <Link href="#" variant="ghost" size="sm">Status</Link>
        <Link href="#" variant="ghost" size="sm">Privacy</Link>
        <Link href="#" variant="ghost" size="sm">Terms</Link>
      </nav>
    </div>
  )
}
```

### Styles

Underline, no underline, arrow, outline and size options.

```tsx
"use client"

import {
  Link
} from "@glinui/ui"

export function LinkStatesExample() {
  return (
    <div className="mx-auto grid w-full max-w-md gap-3">
      <Link href="#">Default underlined link</Link>
      <Link href="#" underline={false}>Link without underline</Link>
      <Link href="#" variant="arrow">Arrow link</Link>
      <Link href="#" variant="outline">Outline link</Link>
      <Link href="#" size="lg">Large link</Link>
    </div>
  )
}
```

### Inline and footer links

Links inside running text and in a footer column group.

```tsx
import { Heading, Link, Text } from "@glinui/ui"

const columns: Array<[string, string[]]> = [
  ["Product", ["Features", "Pricing", "Changelog", "Status"]],
  ["Developers", ["Documentation", "API reference", "SDKs", "Community"]],
  ["Company", ["About", "Careers", "Press kit", "Contact"]]
]

export function LinkShowcase() {
  return (
    <div className="flex w-full max-w-2xl flex-col gap-6 rounded-2xl border border-[var(--line-soft)] bg-[var(--surface-1)] p-6 text-left">
      <Text variant="muted">
        Read the <Link href="/guide">migration guide</Link> before upgrading, then check the <Link href="/api" variant="outline">API reference</Link> for removed fields.
        Need help? <Link href="/support" variant="arrow">Talk to support</Link>
      </Text>
      <nav aria-label="Footer" className="grid grid-cols-2 gap-6 border-t border-[var(--line-soft)] pt-6 sm:grid-cols-3">
        {columns.map(([title, links]) => (
          <div key={title} className="flex flex-col gap-2">
            <Heading level={3} size="sm">{title}</Heading>
            <ul className="flex flex-col gap-1.5">
              {links.map((label) => (
                <li key={label}><Link href="#" variant="ghost" underline={false} size="sm">{label}</Link></li>
              ))}
            </ul>
          </div>
        ))}
      </nav>
    </div>
  )
}
```

## Props

### LinkProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `hideArrow?` | `boolean` | `false` | Arrow variant only: hide the trailing arrow icon. |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from linkVariants. |
| `underline?` | `"true" \| "false"` | `true` | Variant option from linkVariants. |
| `variant?` | `"default" \| "glass" \| "outline" \| "ghost" \| "arrow"` | `"default"` | Variant option from linkVariants. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`, `glass`, `outline`, `ghost`, `arrow`.

## Accessibility

- Uses semantic anchor element with keyboard navigation.
- Focus-visible ring is applied for keyboard users.
- `Link` renders a native `<a>` element, which is keyboard-focusable by default.
- A visible focus ring is applied via the design token system, do not suppress it with `outline-none` without a custom focus style.
- For external links, always include `rel="noopener noreferrer"` to prevent tab-napping.
- If the link text is not self-descriptive (e.g. "click here"), add an `aria-label` describing the destination.

Keyboard:

| Key | Action |
| --- | --- |
| Enter | Open the link destination. |

ARIA:

- `role="link"` native
- `aria-current` for active navigation states

- Reduced motion: Hover/focus styles are color-only and respect reduced motion settings. `Link` has no animation and is unaffected by `prefers-reduced-motion`.

---

# Input

> Single-line input with glass, liquid, matte, and utility variants.

- id: `input`
- type: primitive
- category: Forms and inputs
- tags: primitive
- docs: https://glinui.com/docs/components/radix/input
- markdown: https://glinui.com/md/input.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add input
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/input.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Input, CONTROL_LEGACY_VARIANTS, CONTROL_SIZE_CLASSES, GlinProvider, GLIN_MOTIONS, GLIN_ENGINES, GLIN_SURFACES, GLIN_STYLES } from "@glinui/ui"
```

## Usage

A sign-up form with helper text, live error and success states. Try admin as the username.

```tsx
"use client"

import { useState } from "react"
import { CheckCircle } from "@phosphor-icons/react"
import { Button, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Field, FieldControl, FieldDescription, FieldError, FieldLabel, Input } from "@glinui/ui"

export function InputSignUpForm() {
  const [email, setEmail] = useState("maya@acme")
  const [handle, setHandle] = useState("mayachen")
  const emailInvalid = email.length > 0 && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
  const handleTaken = handle === "admin"
  const handleOk = handle.length >= 3 && !handleTaken

  return (
    <Card className="w-full max-w-md">
      <CardHeader>
        <CardTitle>Create your account</CardTitle>
        <CardDescription>Free for teams up to five people. No card needed.</CardDescription>
      </CardHeader>
      <CardContent>
        <form className="grid gap-4" onSubmit={(event) => event.preventDefault()} noValidate>
          <Field>
            <FieldLabel>Full name</FieldLabel>
            <FieldControl><Input autoComplete="name" defaultValue="Maya Chen" /></FieldControl>
            <FieldDescription>Shown on invoices and in your team directory.</FieldDescription>
          </Field>
          <Field invalid={emailInvalid}>
            <FieldLabel>Work email</FieldLabel>
            <FieldControl>
              <Input type="email" autoComplete="email" value={email} onChange={(event) => setEmail(event.target.value)} />
            </FieldControl>
            {emailInvalid ? <FieldError>Enter a full address like maya@acme.com.</FieldError> : null}
          </Field>
          <Field invalid={handleTaken}>
            <FieldLabel>Username</FieldLabel>
            <FieldControl>
              <Input autoComplete="username" value={handle} onChange={(event) => setHandle(event.target.value.trim())} />
            </FieldControl>
            {handleTaken ? <FieldError>That username is taken. Try another.</FieldError> : null}
            {handleOk ? (
              <p className="flex items-center gap-1.5 text-sm text-[color:var(--tone-success-text)]">
                <CheckCircle weight="fill" className="size-4" aria-hidden />
                glin.app/{handle} is available
              </p>
            ) : null}
          </Field>
        </form>
      </CardContent>
      <CardFooter>
        <Button variant="solid" tone="accent" className="w-full" disabled={emailInvalid || handleTaken}>
          Create account
        </Button>
      </CardFooter>
    </Card>
  )
}
```

### Variants

glinr (default) is the inset well, plain is the flat shadcn field. Each state is AA readable on every stage backdrop.

```tsx
import { Input } from "@glinui/ui"

export function Demo() {
  return (
    <div className="grid gap-3 sm:grid-cols-2">
      <Input variant="glinr" placeholder="glinr" />
      <Input variant="solid" placeholder="solid" />
      <Input variant="plain" placeholder="plain" />
      <Input variant="soft" placeholder="soft" />
      <Input variant="outline" placeholder="outline" />
      <Input variant="ghost" placeholder="ghost" />
    </div>
  )
}
```

### Glass (opt-in)

Glass is opt-in and needs a backdrop behind it: pick Photo or Vivid in the stage backdrop switcher.

```tsx
import { Input } from "@glinui/ui"

export function Demo() {
  return (
    <Input variant="glass" placeholder="Glass input" />
  )
}
```

## Props

### InputProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size?` | `unknown` | `"md"` | Variant option from inputSizeVariants. |
| `variant?` | `ControlVariantProp` |  | Surface look. Omit to follow the ambient design style (glinr = inset well, minimal = plain). Also: solid, plain, soft, outline, ghost, gl... |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Native `input` semantics.
- Visible focus ring on `:focus-visible`.
- Pair with `<label>` or `aria-label` for screen readers.
- Always associate an `<Input>` with a visible `<label>` or provide an `aria-label`.
- Placeholder text is not a label; treat it as a hint only.
- The `type` prop maps directly to the native input element, enabling built-in browser behaviors (e.g., `type="email"` triggers mobile keyboards).
- Disabled inputs are announced as such by screen readers via the native `disabled` attribute.

Keyboard:

| Key | Action |
| --- | --- |
| Tab | Move focus to the input. |

ARIA:

- `role="textbox"` native
- `aria-invalid` for validation

- Reduced motion: Focus transitions use tokenized timing. Input does not use animation to communicate state changes; focus and hover styles are purely visual.

---

# Textarea

> Multi-line input with glass, liquid, matte, and utility variants.

- id: `textarea`
- type: primitive
- category: Forms and inputs
- tags: primitive
- docs: https://glinui.com/docs/components/radix/textarea
- markdown: https://glinui.com/md/textarea.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add textarea
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/textarea.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Textarea, CONTROL_LEGACY_VARIANTS, CONTROL_SIZE_CLASSES, GlinProvider, GLIN_MOTIONS, GLIN_ENGINES, GLIN_SURFACES, GLIN_STYLES } from "@glinui/ui"
```

## Usage

A feedback form with a live character counter.

```tsx
"use client"

import { useState } from "react"
import { Button, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Field, FieldControl, FieldDescription, FieldLabel, Select, Textarea } from "@glinui/ui"

export function TextareaFeedbackForm() {
  const [message, setMessage] = useState("The export button is hidden on narrow screens, so I could not download my invoices from my phone.")
  const limit = 280
  return (
    <Card className="w-full max-w-md">
      <CardHeader>
        <CardTitle>Send feedback</CardTitle>
        <CardDescription>Tell us what is slowing you down. A person reads every message.</CardDescription>
      </CardHeader>
      <CardContent className="grid gap-4">
        <Field>
          <FieldLabel>Topic</FieldLabel>
          <FieldControl>
            <Select
              defaultValue="bug"
              options={[
                { value: "bug", label: "Something is broken" },
                { value: "idea", label: "Feature idea" },
                { value: "billing", label: "Billing question" }
              ]}
            />
          </FieldControl>
        </Field>
        <Field>
          <FieldLabel>Message</FieldLabel>
          <FieldControl>
            <Textarea rows={4} maxLength={limit} value={message} onChange={(event) => setMessage(event.target.value)} />
          </FieldControl>
          <FieldDescription>{limit - message.length} characters left.</FieldDescription>
        </Field>
      </CardContent>
      <CardFooter className="flex items-center justify-end gap-2">
        <Button variant="ghost" onClick={() => setMessage("")}>Clear</Button>
        <Button variant="solid" tone="accent" disabled={message.trim().length === 0}>Send feedback</Button>
      </CardFooter>
    </Card>
  )
}
```

### Variants

```tsx
import { Textarea } from "@glinui/ui"

export function Demo() {
  return (
    <div className="grid gap-3 sm:grid-cols-2">
      <Textarea variant="glinr" placeholder="glinr" rows={2} />
      <Textarea variant="solid" placeholder="solid" rows={2} />
      <Textarea variant="plain" placeholder="plain" rows={2} />
      <Textarea variant="soft" placeholder="soft" rows={2} />
      <Textarea variant="outline" placeholder="outline" rows={2} />
      <Textarea variant="ghost" placeholder="ghost" rows={2} />
    </div>
  )
}
```

### Glass (opt-in)

Glass is opt-in and needs a backdrop behind it: pick Photo or Vivid in the stage backdrop switcher.

```tsx
import { Textarea } from "@glinui/ui"

export function Demo() {
  return (
    <Textarea variant="glass" placeholder="Glass textarea" />
  )
}
```

## Props

### TextareaProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from textareaSizeVariants. |
| `variant?` | `ControlVariantProp` |  | Surface look. Omit to follow the ambient design style. Same vocabulary as Input. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Native `textarea` semantics.
- Pair with `<label>` or `aria-label` for screen readers.
- Always pair a `<Textarea>` with a `<label>` using `htmlFor` or supply an `aria-label`.
- Placeholder text is not a substitute for labeling.
- The `rows` attribute provides a visible size hint; use CSS `min-height` / `max-height` for precise control.
- Disabled textareas convey their state through the native `disabled` attribute, readable by all major screen readers.

Keyboard:

| Key | Action |
| --- | --- |
| Tab | Move focus to the textarea. |

ARIA:

- `role="textbox"` native
- `aria-invalid` for validation

- Reduced motion: No animation dependencies. Textarea has no built-in animation. Focus ring and border transitions respect the user's `prefers-reduced-motion` setting automatically via Tailwind.

---

# Input Group

> An input with inline or block addons such as icons, text and buttons in one shared container.

- id: `input-group`
- type: primitive
- category: Forms and inputs
- tags: primitive
- docs: https://glinui.com/docs/components/radix/input-group
- markdown: https://glinui.com/md/input-group.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add input-group
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/input-group.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { InputGroup, InputGroupAddon, InputGroupButton, InputGroupText, InputGroupInput, InputGroupTextarea, CONTROL_LEGACY_VARIANTS, CONTROL_SIZE_CLASSES } from "@glinui/ui"
```

## Usage

Icon, text, button and keyboard hint addons share one container.

```tsx
import { Link as LinkIcon, MagnifyingGlass } from "@phosphor-icons/react"
import { Card, CardContent, CardDescription, CardHeader, CardTitle, InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput, InputGroupText, Kbd } from "@glinui/ui"

export function InputGroupShare() {
  return (
    <Card className="w-full max-w-md">
      <CardHeader>
        <CardTitle>Share this board</CardTitle>
        <CardDescription>Anyone with the link can view. Only members can comment.</CardDescription>
      </CardHeader>
      <CardContent className="grid gap-4">
        <InputGroup>
          <InputGroupAddon><LinkIcon /></InputGroupAddon>
          <InputGroupInput aria-label="Share link" readOnly defaultValue="glin.app/b/atlas-roadmap" />
          <InputGroupAddon align="inline-end">
            <InputGroupButton variant="ghost">Copy</InputGroupButton>
          </InputGroupAddon>
        </InputGroup>
        <InputGroup>
          <InputGroupAddon><InputGroupText>https://</InputGroupText></InputGroupAddon>
          <InputGroupInput aria-label="Custom domain" defaultValue="roadmap" />
          <InputGroupAddon align="inline-end"><InputGroupText>.glin.app</InputGroupText></InputGroupAddon>
        </InputGroup>
        <InputGroup>
          <InputGroupAddon><MagnifyingGlass /></InputGroupAddon>
          <InputGroupInput aria-label="Invite by email" placeholder="Invite by email" />
          <InputGroupAddon align="inline-end"><Kbd>Enter</Kbd></InputGroupAddon>
        </InputGroup>
      </CardContent>
    </Card>
  )
}
```

### Variants

```tsx
import { InputGroup, InputGroupInput } from "@glinui/ui"

export function Demo() {
  return (
    <div className="grid gap-3 sm:grid-cols-2">
      <InputGroup variant="glinr">
        <InputGroupInput aria-label="glinr" placeholder="glinr" />
      </InputGroup>
      <InputGroup variant="solid">
        <InputGroupInput aria-label="solid" placeholder="solid" />
      </InputGroup>
      <InputGroup variant="plain">
        <InputGroupInput aria-label="plain" placeholder="plain" />
      </InputGroup>
      <InputGroup variant="soft">
        <InputGroupInput aria-label="soft" placeholder="soft" />
      </InputGroup>
      <InputGroup variant="outline">
        <InputGroupInput aria-label="outline" placeholder="outline" />
      </InputGroup>
      <InputGroup variant="ghost">
        <InputGroupInput aria-label="ghost" placeholder="ghost" />
      </InputGroup>
    </div>
  )
}
```

### Glass (opt-in)

Glass is opt-in and needs a backdrop behind it: pick Photo or Vivid in the stage backdrop switcher.

```tsx
import { InputGroup, InputGroupAddon, InputGroupText, InputGroupTextarea } from "@glinui/ui"

export function Demo() {
  return (
    <InputGroup variant="glass">
      <InputGroupTextarea aria-label="Message" placeholder="Write a message..." />
      <InputGroupAddon align="block-end"><InputGroupText>0 / 280</InputGroupText></InputGroupAddon>
    </InputGroup>
  )
}
```

## Props

### InputGroupAddonProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align?` | `"inline-start" \| "inline-end" \| "block-start" \| "block-end"` | `"inline-start"` | Variant option from inputGroupAddonVariants. |

### InputGroupButtonProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size?` | `"xs" \| "sm"` | `"xs"` |  |

### InputGroupProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size?` | `"sm" \| "md" \| "lg"` | `"xs"` | Variant option from inputGroupSizeVariants. |
| `variant?` | `ControlVariantProp` | `"ghost"` | Surface look, shared with Input. Omit to follow the ambient design style (glinr = inset well). The group owns the surface; the control in... |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Container is `role="group"`; the control keeps native input semantics.
- Focus ring and `aria-invalid` styling move to the whole container.
- Icon addons are decorative; label the control itself.

Keyboard:

| Key | Action |
| --- | --- |
| Tab | Move between the control and addon buttons. |

ARIA:

- `aria-invalid` on the control styles the container
- `aria-label` on the control when no visible label

- Reduced motion: Border and shadow transitions are disabled under prefers-reduced-motion.

---

# Input OTP

> A one-time-code input with segmented slots, paste and autofill support.

- id: `input-otp`
- type: primitive
- category: Forms and inputs
- tags: primitive
- docs: https://glinui.com/docs/components/radix/input-otp
- markdown: https://glinui.com/md/input-otp.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add input-otp
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/input-otp.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { REGEXP_ONLY_DIGITS, REGEXP_ONLY_CHARS, REGEXP_ONLY_DIGITS_AND_CHARS, InputOTP, InputOTPGroup, InputOTPSlot, InputOTPSeparator, CONTROL_LEGACY_VARIANTS } from "@glinui/ui"
```

## Usage

A verify-email card with a resend countdown. Typing a sixth digit verifies.

```tsx
"use client"

import { useEffect, useState } from "react"
import { EnvelopeSimple, ShieldCheck } from "@phosphor-icons/react"
import { Button, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, InputOTP, InputOTPGroup, InputOTPSeparator, InputOTPSlot } from "@glinui/ui"

export function InputOtpVerify() {
  const [code, setCode] = useState("482")
  const [seconds, setSeconds] = useState(24)
  const [verified, setVerified] = useState(false)
  useEffect(() => {
    if (seconds <= 0) return
    const id = setTimeout(() => setSeconds((value) => value - 1), 1000)
    return () => clearTimeout(id)
  }, [seconds])

  return (
    <Card className="w-full max-w-sm">
      <CardHeader>
        <div className="flex size-10 items-center justify-center rounded-full bg-[var(--surface-1)] text-[var(--color-accent)]">
          <EnvelopeSimple weight="duotone" className="size-5" aria-hidden />
        </div>
        <CardTitle>Check your email</CardTitle>
        <CardDescription>We sent a 6 digit code to maya@acme.com. It expires in 10 minutes.</CardDescription>
      </CardHeader>
      <CardContent className="grid gap-3">
        <InputOTP
          maxLength={6}
          value={code}
          onChange={setCode}
          onComplete={() => setVerified(true)}
          aria-label="Verification code"
        >
          <InputOTPGroup>
            {[0, 1, 2].map((index) => <InputOTPSlot key={index} index={index} />)}
          </InputOTPGroup>
          <InputOTPSeparator />
          <InputOTPGroup>
            {[3, 4, 5].map((index) => <InputOTPSlot key={index} index={index} />)}
          </InputOTPGroup>
        </InputOTP>
        <p className="min-h-5 text-sm text-[var(--color-muted)]" aria-live="polite">
          {verified ? (
            <span className="flex items-center gap-1.5 text-[color:var(--tone-success-text)]">
              <ShieldCheck weight="fill" className="size-4" aria-hidden />
              Email verified
            </span>
          ) : (
            "Paste works too. The code fills every box."
          )}
        </p>
      </CardContent>
      <CardFooter className="flex items-center justify-between gap-3">
        <Button
          variant="ghost"
          size="sm"
          disabled={seconds > 0}
          onClick={() => { setSeconds(30); setCode(""); setVerified(false) }}
        >
          {seconds > 0 ? `Resend in ${seconds}s` : "Resend code"}
        </Button>
        <Button variant="solid" tone="accent" disabled={code.length < 6}>Verify</Button>
      </CardFooter>
    </Card>
  )
}
```

### Variants

```tsx
import { InputOTP, InputOTPGroup, InputOTPSlot } from "@glinui/ui"

export function Demo() {
  return (
    <div className="flex flex-col items-start gap-3">
      <InputOTP maxLength={4} variant="glinr" defaultValue="12" aria-label="glinr">
        <InputOTPGroup>{[0, 1, 2, 3].map((i) => <InputOTPSlot key={i} index={i} />)}</InputOTPGroup>
      </InputOTP>
      <InputOTP maxLength={4} variant="solid" defaultValue="12" aria-label="solid">
        <InputOTPGroup>{[0, 1, 2, 3].map((i) => <InputOTPSlot key={i} index={i} />)}</InputOTPGroup>
      </InputOTP>
      <InputOTP maxLength={4} variant="plain" defaultValue="12" aria-label="plain">
        <InputOTPGroup>{[0, 1, 2, 3].map((i) => <InputOTPSlot key={i} index={i} />)}</InputOTPGroup>
      </InputOTP>
      <InputOTP maxLength={4} variant="soft" defaultValue="12" aria-label="soft">
        <InputOTPGroup>{[0, 1, 2, 3].map((i) => <InputOTPSlot key={i} index={i} />)}</InputOTPGroup>
      </InputOTP>
      <InputOTP maxLength={4} variant="outline" defaultValue="12" aria-label="outline">
        <InputOTPGroup>{[0, 1, 2, 3].map((i) => <InputOTPSlot key={i} index={i} />)}</InputOTPGroup>
      </InputOTP>
      <InputOTP maxLength={4} variant="ghost" defaultValue="12" aria-label="ghost">
        <InputOTPGroup>{[0, 1, 2, 3].map((i) => <InputOTPSlot key={i} index={i} />)}</InputOTPGroup>
      </InputOTP>
    </div>
  )
}
```

### Alphanumeric

```tsx
import { InputOTP, InputOTPGroup, InputOTPSlot, REGEXP_ONLY_DIGITS_AND_CHARS } from "@glinui/ui"

export function Demo() {
  return (
    <InputOTP maxLength={4} pattern={REGEXP_ONLY_DIGITS_AND_CHARS} defaultValue="A1">
      <InputOTPGroup>{[0, 1, 2, 3].map((i) => <InputOTPSlot key={i} index={i} />)}</InputOTPGroup>
    </InputOTP>
  )
}
```

## Props

### InputOTPProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `containerClassName?` | `string` |  | Class for the outer container. |
| `defaultValue?` | `string` | `""` | Initial value for uncontrolled usage. |
| `maxLength` | `number` |  | Number of characters. Required. |
| `onChange?` | `(value: string) => void` |  | Fires with the new value on every accepted change. |
| `onComplete?` | `(value: string) => void` |  | Fires once when the value reaches maxLength. |
| `pattern?` | `string` | `REGEXP_ONLY_DIGITS` | Regular expression source the whole value must match, e.g. REGEXP_ONLY_DIGITS. |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from inputOTPSlotVariants. |
| `value?` | `string` |  | Controlled value. |
| `variant?` | `ControlVariantProp` |  | Surface look of the slots. Omit to follow the ambient design style. Same vocabulary as Input. |

### InputOTPSlotProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `index` | `number` |  | Zero-based position this slot renders. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- A single real `input` carries focus, value and the accessible name, so screen readers announce one field, not N boxes.
- Slots are `aria-hidden` visuals.
- Paste and one-time-code autofill fill every slot at once.
- Default `aria-label` is Verification code; override it.

Keyboard:

| Key | Action |
| --- | --- |
| 0-9 / characters | Fill the active slot and advance. |
| Backspace | Delete the previous character. |
| Arrow Left / Right | Move the caret (mirrored in RTL). |
| Home / End | Jump to first slot or end. |
| Ctrl/Cmd + V | Paste a full code. |

ARIA:

- `aria-label` on the input
- `aria-invalid` highlights every slot
- `inputmode="numeric"` for digit patterns

- Reduced motion: The blinking caret and colour transitions are disabled under prefers-reduced-motion.

---

# Select

> Native select with glass, liquid, matte, and utility variants.

- id: `select`
- type: primitive
- category: Forms and inputs
- tags: primitive
- docs: https://glinui.com/docs/components/radix/select
- markdown: https://glinui.com/md/select.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add select
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/select.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Select, CONTROL_LEGACY_VARIANTS, CONTROL_SIZE_CLASSES, GlinProvider, GLIN_MOTIONS, GLIN_ENGINES, GLIN_SURFACES, GLIN_STYLES } from "@glinui/ui"
```

## Usage

A settings panel with a label, helper text and a select per row.

```tsx
import { Card, CardContent, CardDescription, CardHeader, CardTitle, Field, FieldControl, FieldDescription, FieldLabel, Select } from "@glinui/ui"

export function SelectPreferences() {
  return (
    <Card className="w-full max-w-xl">
      <CardHeader>
        <CardTitle>Preferences</CardTitle>
        <CardDescription>Applies to every workspace you belong to.</CardDescription>
      </CardHeader>
      <CardContent className="divide-y divide-border/60">
        <Field orientation="responsive" className="py-3 first:pt-0">
          <div className="grid flex-auto gap-0.5">
            <FieldLabel>Language</FieldLabel>
            <FieldDescription>Used for menus and emails.</FieldDescription>
          </div>
          <FieldControl>
            <Select
              className="md:w-48"
              defaultValue="en"
              options={[
                { value: "en", label: "English" },
                { value: "de", label: "Deutsch" },
                { value: "fr", label: "Francais" },
                { value: "ja", label: "Japanese" }
              ]}
            />
          </FieldControl>
        </Field>
        <Field orientation="responsive" className="py-3">
          <div className="grid flex-auto gap-0.5">
            <FieldLabel>Time zone</FieldLabel>
            <FieldDescription>Schedules and digests follow it.</FieldDescription>
          </div>
          <FieldControl>
            <Select
              className="md:w-48"
              defaultValue="pt"
              options={[
                { value: "pt", label: "Pacific (UTC-8)" },
                { value: "et", label: "Eastern (UTC-5)" },
                { value: "cet", label: "Central Europe (UTC+1)" },
                { value: "ist", label: "India (UTC+5:30)" }
              ]}
            />
          </FieldControl>
        </Field>
        <Field orientation="responsive" className="py-3 last:pb-0">
          <div className="grid flex-auto gap-0.5">
            <FieldLabel>Date format</FieldLabel>
            <FieldDescription>How dates appear in tables.</FieldDescription>
          </div>
          <FieldControl>
            <Select
              className="md:w-48"
              defaultValue="iso"
              options={[
                { value: "iso", label: "2026-10-07" },
                { value: "us", label: "10/07/2026" },
                { value: "eu", label: "07/10/2026" }
              ]}
            />
          </FieldControl>
        </Field>
      </CardContent>
    </Card>
  )
}
```

### Sizes

```tsx
import { Select } from "@glinui/ui"

const opts = [{ value: "a", label: "Alpha" }, { value: "b", label: "Beta" }]

export function Demo() {
  return (
    <div className="space-y-3 max-w-xs">
      <Select size="sm" options={opts} placeholder="Small" />
      <Select size="md" options={opts} placeholder="Medium" />
      <Select size="lg" options={opts} placeholder="Large" />
    </div>
  )
}
```

### Variants

```tsx
import { Select } from "@glinui/ui"

export function Demo() {
  return (
    <div className="grid gap-3 sm:grid-cols-2">
      <Select variant="glinr" options={[{ value: "a", label: "Alpha" }, { value: "b", label: "Beta" }]} placeholder="glinr" />
      <Select variant="solid" options={[{ value: "a", label: "Alpha" }, { value: "b", label: "Beta" }]} placeholder="solid" />
      <Select variant="plain" options={[{ value: "a", label: "Alpha" }, { value: "b", label: "Beta" }]} placeholder="plain" />
      <Select variant="soft" options={[{ value: "a", label: "Alpha" }, { value: "b", label: "Beta" }]} placeholder="soft" />
      <Select variant="outline" options={[{ value: "a", label: "Alpha" }, { value: "b", label: "Beta" }]} placeholder="outline" />
      <Select variant="ghost" options={[{ value: "a", label: "Alpha" }, { value: "b", label: "Beta" }]} placeholder="ghost" />
    </div>
  )
}
```

## Props

### SelectProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` | `SelectOption[]` |  |  |
| `placeholder?` | `string` |  |  |
| `size?` | `unknown` | `"md"` | Variant option from selectSizeVariants. |
| `variant?` | `ControlVariantProp` |  | Surface look. Omit to follow the ambient design style. Same vocabulary as Input. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Native `select` semantics with keyboard navigation.
- Pair with `<label>` or `aria-label`.
- Renders a native `<select>` element for maximum browser and assistive technology compatibility.
- Pair with a `<label>` using `htmlFor` or provide an `aria-label` when no visible label exists.
- Placeholder text should not be used as the sole accessible label.
- Disabled individual options use the native `disabled` attribute on `<option>` elements.

Keyboard:

| Key | Action |
| --- | --- |
| Enter / Space | Open the select dropdown. |
| Arrow Up / Down | Navigate options. |

ARIA:

- `role="combobox"` native
- `aria-expanded`
- `aria-selected`

- Reduced motion: No animation dependencies. Select does not use custom animations; open/close behavior is controlled by the browser's native dropdown.

---

# Combobox

> A searchable select built from Popover and Command.

- id: `combobox`
- type: primitive
- category: Forms and inputs
- tags: primitive
- docs: https://glinui.com/docs/components/radix/combobox
- markdown: https://glinui.com/md/combobox.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add combobox
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/combobox.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Combobox, CONTROL_LEGACY_VARIANTS, CONTROL_SIZE_CLASSES, GlinProvider, GLIN_MOTIONS, GLIN_ENGINES, GLIN_SURFACES, GLIN_STYLES } from "@glinui/ui"
```

## Usage

Combobox is single select only. For multiple selection, compose Popover with Command, or use a checkbox group.

A searchable picker kept in sync with quick-pick chips. Logos come from the docs BrandIcon helper; use your own marks in your app.

```tsx
"use client"

import { useState } from "react"
import { Button, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Combobox, Field, FieldControl, FieldLabel } from "@glinui/ui"
import { BrandIcon } from "@/components/brand/brand-icon"

export function ComboboxFrameworkPicker() {
  const frameworks = [
    { value: "nextjs", label: "Next.js", keywords: ["react", "vercel"] },
    { value: "remix", label: "Remix", keywords: ["react"] },
    { value: "astro", label: "Astro", keywords: ["islands"] },
    { value: "nuxt", label: "Nuxt", keywords: ["vue"] },
    { value: "vite", label: "Vite", keywords: ["spa"] }
  ] as const
  const [value, setValue] = useState("nextjs")
  const current = frameworks.find((item) => item.value === value)
  return (
    <Card className="w-full max-w-md">
      <CardHeader>
        <CardTitle>New project</CardTitle>
        <CardDescription>Pick the framework we should scaffold. Type to filter the list.</CardDescription>
      </CardHeader>
      <CardContent className="grid gap-4">
        <Field>
          <FieldLabel>Framework</FieldLabel>
          <FieldControl>
            <Combobox
              options={frameworks.map((item) => ({ ...item, keywords: [...item.keywords] }))}
              value={value}
              onValueChange={setValue}
              placeholder="Select a framework"
              searchPlaceholder="Search frameworks"
              aria-label="Framework"
            />
          </FieldControl>
        </Field>
        <div className="flex flex-wrap items-center gap-2" role="group" aria-label="Frameworks">
          {frameworks.map((item) => (
            <button
              key={item.value}
              type="button"
              aria-pressed={item.value === value}
              onClick={() => setValue(item.value)}
              className="flex items-center gap-2 rounded-full border border-border/60 px-3 py-1.5 text-sm text-foreground outline-none transition-colors hover:bg-[var(--surface-1)] focus-visible:ring-2 focus-visible:ring-[var(--color-accent)] aria-pressed:border-[var(--color-accent)] aria-pressed:bg-[var(--surface-1)]"
            >
              <BrandIcon name={item.value} size={16} />
              {item.label}
            </button>
          ))}
        </div>
      </CardContent>
      <CardFooter className="flex items-center justify-between gap-3">
        <span className="text-sm text-[var(--color-muted)]">{current ? `${current.label} starter selected` : "Nothing selected"}</span>
        <Button variant="solid" tone="accent" disabled={!current}>Create project</Button>
      </CardFooter>
    </Card>
  )
}
```

### Variants

```tsx
import { Combobox } from "@glinui/ui"

const frameworks = [
  { value: "next", label: "Next.js" },
  { value: "remix", label: "Remix" },
  { value: "astro", label: "Astro", keywords: ["islands"] },
  { value: "nuxt", label: "Nuxt" },
  { value: "sveltekit", label: "SvelteKit" }
]

export function Demo() {
  return (
    <div className="grid gap-3 sm:grid-cols-2">
      <Combobox variant="glinr" options={frameworks} aria-label="glinr" placeholder="glinr" />
      <Combobox variant="solid" options={frameworks} aria-label="solid" placeholder="solid" />
      <Combobox variant="plain" options={frameworks} aria-label="plain" placeholder="plain" />
      <Combobox variant="soft" options={frameworks} aria-label="soft" placeholder="soft" />
      <Combobox variant="outline" options={frameworks} aria-label="outline" placeholder="outline" />
      <Combobox variant="ghost" options={frameworks} aria-label="ghost" placeholder="ghost" />
    </div>
  )
}
```

### Glass (opt-in)

Glass is opt-in and needs a backdrop behind it: pick Photo or Vivid in the stage backdrop switcher.

```tsx
import { Combobox } from "@glinui/ui"

const frameworks = [
  { value: "next", label: "Next.js" },
  { value: "remix", label: "Remix" },
  { value: "astro", label: "Astro", keywords: ["islands"] },
  { value: "nuxt", label: "Nuxt" },
  { value: "sveltekit", label: "SvelteKit" }
]

export function Demo() {
  return <Combobox variant="glass" options={frameworks} aria-label="Framework" />
}
```

## Props

### ComboboxProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby?` | `string` |  |  |
| `aria-invalid?` | `boolean \| "true" \| "false"` |  |  |
| `aria-label?` | `string` |  |  |
| `aria-labelledby?` | `string` |  |  |
| `className?` | `string` |  |  |
| `clearable?` | `boolean` | `false` | Allow selecting the active option again to clear it. |
| `contentClassName?` | `string` |  | Extra class for the popover panel. |
| `defaultValue?` | `string` | `""` | Initial value for uncontrolled usage. |
| `disabled?` | `boolean` |  |  |
| `emptyText?` | `string` | `"No results found."` | Message shown when no option matches. |
| `id?` | `string` |  |  |
| `name?` | `string` |  | Form field name; renders a hidden input with the value. |
| `onOpenChange?` | `(open: boolean) => void` |  |  |
| `onValueChange?` | `(value: string) => void` |  | Fires when the selection changes. Empty string means cleared. |
| `open?` | `boolean` |  | Controlled open state. |
| `options` | `ComboboxOption[]` |  |  |
| `placeholder?` | `string` | `"Select an option"` | Trigger text when nothing is selected. |
| `searchPlaceholder?` | `string` | `"Search..."` | Placeholder inside the search input. |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from comboboxSizeVariants. |
| `value?` | `string` |  | Controlled selected value. |
| `variant?` | `ControlVariantProp` |  | Trigger look. Omit to follow the ambient design style (glinr = inset well). Same vocabulary as Input. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Trigger is `role="combobox"` with `aria-expanded`, `aria-haspopup="listbox"` and `aria-controls`.
- The panel is a filterable listbox (Command) with a labelled search field.
- Focus returns to the trigger when the panel closes.
- Pass `aria-label` or label it through Field.

Keyboard:

| Key | Action |
| --- | --- |
| Enter / Space / Arrow Down | Open the list from the trigger. |
| Type | Filter options. |
| Arrow Up / Down | Move the highlighted option. |
| Enter | Select the highlighted option. |
| Escape | Close without changing the value. |

ARIA:

- `role="combobox"` and `aria-expanded` on trigger
- `aria-invalid` and `aria-describedby` pass through
- `role="listbox"` and `role="option"` from cmdk

- Reduced motion: Panel open and close animations are disabled under prefers-reduced-motion.

---

# Field

> Accessible form field layout that wires labels, descriptions and errors to a control.

- id: `field`
- type: primitive
- category: Forms and inputs
- tags: primitive
- docs: https://glinui.com/docs/components/radix/field
- markdown: https://glinui.com/md/field.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add field
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/field.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Field, FieldControl, FieldLabel, FieldTitle, FieldContent, FieldDescription, FieldError, FieldGroup } from "@glinui/ui"
```

## Usage

FieldControl wires one child control to its Field. It clones the child and injects the generated id (matching the label htmlFor), aria-describedby pointing at the description and error, aria-invalid when an error is present and aria-required. Put exactly one control inside it.

Unlike shadcn Field, which leaves id and aria wiring to you, Glin UI Field does it through FieldControl, so labels, hints and errors stay connected without manual ids. Controls rendered outside FieldControl are not wired.

A full checkout form: fieldsets, descriptions, an error and a grouped card input.

```tsx
import { CreditCard } from "@phosphor-icons/react"
import { Button, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Checkbox, Field, FieldControl, FieldDescription, FieldError, FieldGroup, FieldLabel, FieldLegend, FieldSet, Input, InputGroup, InputGroupAddon, InputGroupInput } from "@glinui/ui"

export function FieldCheckoutForm() {
  return (
    <Card className="w-full max-w-xl">
      <CardHeader>
        <CardTitle>Checkout</CardTitle>
        <CardDescription>Studio keyboard, 75%. $129.00 with free shipping.</CardDescription>
      </CardHeader>
      <CardContent>
        <form className="grid gap-6" onSubmit={(event) => event.preventDefault()}>
          <FieldSet>
            <FieldLegend>Contact</FieldLegend>
            <FieldGroup>
              <Field>
                <FieldLabel>Email</FieldLabel>
                <FieldControl><Input type="email" autoComplete="email" defaultValue="maya@acme.com" /></FieldControl>
                <FieldDescription>We send the receipt and tracking here.</FieldDescription>
              </Field>
            </FieldGroup>
          </FieldSet>
          <FieldSet>
            <FieldLegend>Shipping</FieldLegend>
            <FieldGroup>
              <Field>
                <FieldLabel>Street address</FieldLabel>
                <FieldControl><Input autoComplete="street-address" defaultValue="410 Alder Street" /></FieldControl>
              </Field>
              <div className="grid gap-4 sm:grid-cols-2">
                <Field>
                  <FieldLabel>City</FieldLabel>
                  <FieldControl><Input autoComplete="address-level2" defaultValue="Portland" /></FieldControl>
                </Field>
                <Field invalid>
                  <FieldLabel>Postal code</FieldLabel>
                  <FieldControl><Input autoComplete="postal-code" defaultValue="972" /></FieldControl>
                  <FieldError>Enter a 5 digit ZIP code.</FieldError>
                </Field>
              </div>
            </FieldGroup>
          </FieldSet>
          <FieldSet>
            <FieldLegend>Payment</FieldLegend>
            <FieldGroup>
              <Field>
                <FieldLabel>Card number</FieldLabel>
                <FieldControl>
                  <InputGroup>
                    <InputGroupAddon><CreditCard /></InputGroupAddon>
                    <InputGroupInput inputMode="numeric" autoComplete="cc-number" placeholder="4242 4242 4242 4242" />
                  </InputGroup>
                </FieldControl>
              </Field>
              <div className="grid grid-cols-2 gap-4">
                <Field>
                  <FieldLabel>Expiry</FieldLabel>
                  <FieldControl><Input autoComplete="cc-exp" placeholder="MM / YY" /></FieldControl>
                </Field>
                <Field>
                  <FieldLabel>CVC</FieldLabel>
                  <FieldControl><Input autoComplete="cc-csc" placeholder="123" /></FieldControl>
                </Field>
              </div>
              <label className="flex items-center gap-2.5 text-sm text-foreground">
                <Checkbox defaultChecked />
                Billing address is the same as shipping
              </label>
            </FieldGroup>
          </FieldSet>
        </form>
      </CardContent>
      <CardFooter>
        <Button variant="solid" tone="accent" className="w-full">Pay $129.00</Button>
      </CardFooter>
    </Card>
  )
}
```

### Label, description, error

```tsx
import { Field, FieldControl, FieldDescription, FieldError, FieldLabel } from "@glinui/ui"
import { Input } from "@glinui/ui"

export function Demo() {
  return (
    <Field>
      <FieldLabel>Email</FieldLabel>
      <FieldControl><Input type="email" placeholder="name@example.com" /></FieldControl>
      <FieldDescription>We never share your email.</FieldDescription>
      <FieldError>Enter a valid email address.</FieldError>
    </Field>
  )
}
```

### Invalid

```tsx
import { Field, FieldControl, FieldError, FieldLabel } from "@glinui/ui"
import { Input } from "@glinui/ui"

export function Demo() {
  return (
    <Field invalid>
      <FieldLabel>Username</FieldLabel>
      <FieldControl><Input defaultValue="a" /></FieldControl>
      <FieldError errors={[{ message: "At least 3 characters" }]} />
    </Field>
  )
}
```

## Props

### FieldErrorProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `errors?` | `Array<{ message?: string } \| undefined>` |  | Error objects (for example from a form library). Messages are de-duplicated. |

### FieldLegendProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant?` | `"legend" \| "label"` | `"legend"` |  |

### FieldProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled?` | `boolean` | `false` | Marks the field disabled. |
| `invalid?` | `boolean` | `false` | Marks the field invalid and wires aria-invalid onto its control. |
| `orientation?` | `"vertical" \| "horizontal" \| "responsive"` | `"vertical"` | Variant option from fieldVariants. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `legend`, `label`.

## Accessibility

- Each Field generates ids so the label `htmlFor`, description and error are wired automatically via FieldControl.
- FieldError uses `role="alert"` so errors are announced.
- `aria-describedby` only lists parts that are rendered.
- FieldSet and FieldLegend use native fieldset and legend semantics.

Keyboard:

| Key | Action |
| --- | --- |
| Tab | Moves through controls; clicking a label focuses its control. |

ARIA:

- `aria-describedby` with description and error ids
- `aria-invalid` when invalid or an error is rendered
- `role="alert"` on errors

- Reduced motion: Field is layout only and has no motion of its own.

---

# Label

> Form label primitive with shared glass-aware variants.

- id: `label`
- type: primitive
- category: Forms and inputs
- tags: primitive
- docs: https://glinui.com/docs/components/radix/label
- markdown: https://glinui.com/md/label.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add label
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/label.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Label } from "@glinui/ui"
```

## Usage

Labels for inputs, a checkbox and a switch, with required and optional markers.

```tsx
import { Card, CardContent, CardDescription, CardHeader, CardTitle, Checkbox, Input, Label, Switch, Textarea } from "@glinui/ui"

export function LabelPairings() {
  return (
    <Card className="w-full max-w-md">
      <CardHeader>
        <CardTitle>Invite a teammate</CardTitle>
        <CardDescription>Labels name a control for everyone, including screen readers.</CardDescription>
      </CardHeader>
      <CardContent className="grid gap-4">
        <div className="grid gap-1.5">
          <Label htmlFor="invite-email">
            Email address <span className="text-[color:var(--tone-danger-text)]" aria-hidden>*</span>
          </Label>
          <Input id="invite-email" type="email" required placeholder="jordan@acme.com" />
        </div>
        <div className="grid gap-1.5">
          <Label htmlFor="invite-note">
            Note <span className="text-xs font-normal text-[var(--color-muted)]">(optional)</span>
          </Label>
          <Textarea id="invite-note" rows={2} placeholder="Say hi, share context" />
        </div>
        <div className="flex items-center gap-2.5">
          <Checkbox id="invite-admin" />
          <Label htmlFor="invite-admin">Make this person an admin</Label>
        </div>
        <div className="flex items-center justify-between gap-3">
          <Label htmlFor="invite-copy">Send me a copy</Label>
          <Switch id="invite-copy" defaultChecked />
        </div>
      </CardContent>
    </Card>
  )
}
```

### Variants

Glass is opt-in and needs a backdrop behind it.

```tsx
import { Label } from "@glinui/ui"

export function Demo() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <Label>Default</Label>
      <Label variant="solid">solid</Label>
      <Label variant="soft">soft</Label>
      <Label variant="outline">outline</Label>
      <Label variant="ghost">ghost</Label>
      <Label variant="glass">glass</Label>
    </div>
  )
}
```

### Variants

```tsx
import { Label } from "@glinui/ui"

export function LabelVariantDemo() {
  return (
    <div className="flex flex-col gap-2">
      <Label variant="default">Default label</Label>
      <Label variant="glass">Glass label</Label>
      <Label variant="outline">Outline label</Label>
      <Label variant="ghost">Ghost label</Label>
    </div>
  )
}
```

## Props

### LabelProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from labelVariants. |
| `variant?` | `"default" \| "glinr" \| "plain" \| "solid" \| "soft" \| "outline" \| "ghost" \| "glass" \| "gradient" \| "f...` |  | Chip treatment. Omit (or glinr, plain, default) for a plain text label that adapts to any ambient style. Also: solid, soft, outline, ghos... |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`, `glinr`, `plain`, `solid`, `soft`, `outline`, `ghost`, `glass`, `gradient`, `frosted`.

## Accessibility

- Uses semantic `<label>` for screen reader form-field association.
- Always provide `htmlFor` to associate the label with its form control, clicking the label should move focus to the input.
- Do not use `Label` as decorative text; prefer `Text` or plain `<span>` elements for non-form contexts.
- When marking required fields, include both the visual asterisk and an `aria-required="true"` attribute on the control.

ARIA:

- `htmlFor` should match form control `id`

- Reduced motion: No motion-dependent behavior. `Label` is a static element with no animation. It is unaffected by `prefers-reduced-motion`.

---

# Checkbox

> Radix checkbox with glass, liquid, matte, and outline surface variants.

- id: `checkbox`
- type: primitive
- category: Forms and inputs
- tags: primitive
- docs: https://glinui.com/docs/components/radix/checkbox
- markdown: https://glinui.com/md/checkbox.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add checkbox
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/checkbox.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Checkbox, CONTROL_LEGACY_VARIANTS, CONTROL_SIZE_CLASSES, GlinProvider, GLIN_MOTIONS, GLIN_ENGINES, GLIN_SURFACES, GLIN_STYLES } from "@glinui/ui"
```

## Usage

A select-all checkbox with an indeterminate state.

```tsx
"use client"

import { useState } from "react"
import { Button, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Checkbox } from "@glinui/ui"

export function CheckboxColumns() {
  const columns = ["Invoice number", "Customer", "Amount", "Status", "Due date"]
  const [selected, setSelected] = useState<string[]>(["Invoice number", "Customer", "Amount"])
  const all = selected.length === columns.length
  return (
    <Card className="w-full max-w-sm">
      <CardHeader>
        <CardTitle>Export columns</CardTitle>
        <CardDescription>{selected.length} of {columns.length} included in the CSV.</CardDescription>
      </CardHeader>
      <CardContent>
        <fieldset className="grid gap-3 border-0 p-0">
          <legend className="sr-only">Columns to export</legend>
          <label className="flex items-center gap-2.5 border-b border-border/60 pb-3 text-sm font-medium text-foreground">
            <Checkbox
              checked={all ? true : selected.length === 0 ? false : "indeterminate"}
              onCheckedChange={(next) => setSelected(next === true ? columns : [])}
            />
            Select all
          </label>
          {columns.map((column) => (
            <label key={column} className="flex items-center gap-2.5 text-sm text-foreground">
              <Checkbox
                checked={selected.includes(column)}
                onCheckedChange={(next) =>
                  setSelected((current) => (next === true ? [...current, column] : current.filter((item) => item !== column)))
                }
              />
              {column}
            </label>
          ))}
        </fieldset>
      </CardContent>
      <CardFooter>
        <Button variant="solid" tone="accent" className="w-full" disabled={selected.length === 0}>Export CSV</Button>
      </CardFooter>
    </Card>
  )
}
```

### Variants and sizes

```tsx
import { Checkbox } from "@glinui/ui"

export function Demo() {
  return (
    <div className="space-y-3">
      <div className="flex items-center gap-3">
        <Checkbox variant="glinr" defaultChecked aria-label="glinr" />
        <Checkbox variant="solid" defaultChecked aria-label="solid" />
        <Checkbox variant="plain" defaultChecked aria-label="plain" />
        <Checkbox variant="soft" defaultChecked aria-label="soft" />
        <Checkbox variant="outline" defaultChecked aria-label="outline" />
        <Checkbox variant="ghost" defaultChecked aria-label="ghost" />
      </div>
      <div className="flex items-center gap-3">
        <Checkbox size="sm" defaultChecked aria-label="Small" />
        <Checkbox size="md" defaultChecked aria-label="Medium" />
        <Checkbox size="lg" defaultChecked aria-label="Large" />
        <Checkbox defaultChecked="indeterminate" aria-label="Indeterminate" />
        <Checkbox aria-invalid aria-label="Invalid" />
      </div>
    </div>
  )
}
```

### Glass (opt-in)

Glass is opt-in and needs a backdrop behind it: pick Photo or Vivid in the stage backdrop switcher.

```tsx
import { Checkbox } from "@glinui/ui"

export function Demo() {
  return (
    <div className="flex items-center gap-3">
      <Checkbox variant="glass" defaultChecked aria-label="Glass checked" />
      <Checkbox variant="glass" aria-label="Glass" />
    </div>
  )
}
```

## Props

### CheckboxProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size?` | `"sm" \| "md" \| "lg"` |  |  |
| `variant?` | `ControlVariantProp` |  | Surface look. Omit to follow the ambient design style (glinr = inset well with a raised accent check). Also: solid, plain, soft, outline,... |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Built on Radix Checkbox with full ARIA support.
- Pair with `<label>` via `htmlFor`.
- Built on `@radix-ui/react-checkbox`, which renders a fully accessible checkbox with keyboard support.
- Always pair with a `<label>` via `htmlFor` / `id` or wrap both in a `<label>` element.
- The `required` prop sets `aria-required` on the underlying button element.
- Space toggles the checkbox; Enter is not handled by default (browser behavior).

Keyboard:

| Key | Action |
| --- | --- |
| Space | Toggle checked state. |

ARIA:

- `role="checkbox"`
- `aria-checked`
- `aria-required`

- Reduced motion: Check icon transitions respect `prefers-reduced-motion`. The check indicator uses a brief scale/fade transition that is suppressed when `prefers-reduced-motion: reduce` is active.

---

# Radio Group

> Mutually exclusive selection control with variant-capable radio items.

- id: `radio-group`
- type: primitive
- category: Forms and inputs
- tags: primitive
- docs: https://glinui.com/docs/components/radix/radio-group
- markdown: https://glinui.com/md/radio-group.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add radio-group
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/radio-group.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { RadioGroup, RadioGroupItem, CONTROL_LEGACY_VARIANTS, CONTROL_SIZE_CLASSES, GlinProvider, GLIN_MOTIONS, GLIN_ENGINES, GLIN_SURFACES } from "@glinui/ui"
```

## Usage

Card-style radios inside labels, with the checked card highlighted.

```tsx
import { Card, CardContent, CardDescription, CardHeader, CardTitle, RadioGroup, RadioGroupItem } from "@glinui/ui"

export function RadioPlanPicker() {
  const plans = [
    { value: "starter", name: "Starter", price: "$0", note: "Up to 3 projects" },
    { value: "pro", name: "Pro", price: "$24", note: "Unlimited projects, SSO" },
    { value: "scale", name: "Scale", price: "$96", note: "Audit log, 99.9% uptime SLA" }
  ]
  return (
    <Card className="w-full max-w-md">
      <CardHeader>
        <CardTitle>Choose a plan</CardTitle>
        <CardDescription>Billed monthly. Change or cancel any time.</CardDescription>
      </CardHeader>
      <CardContent>
        <RadioGroup defaultValue="pro" aria-label="Plan" className="grid gap-2">
          {plans.map((plan) => (
            <label
              key={plan.value}
              className="flex cursor-pointer items-center gap-3 rounded-lg border border-border/60 px-3 py-3 has-[[data-state=checked]]:border-[var(--color-accent)] has-[[data-state=checked]]:bg-[var(--surface-1)]"
            >
              <RadioGroupItem value={plan.value} />
              <span className="min-w-0 flex-1">
                <span className="block text-sm font-medium text-foreground">{plan.name}</span>
                <span className="block text-xs text-[var(--color-muted)]">{plan.note}</span>
              </span>
              <span className="text-sm font-medium tabular-nums text-foreground">{plan.price}<span className="text-xs font-normal text-[var(--color-muted)]">/seat</span></span>
            </label>
          ))}
        </RadioGroup>
      </CardContent>
    </Card>
  )
}
```

### Variants and sizes

```tsx
import { RadioGroup, RadioGroupItem } from "@glinui/ui"

export function Demo() {
  return (
    <div className="space-y-3">
      <RadioGroup defaultValue="glinr" orientation="horizontal" className="flex items-center gap-3">
        <RadioGroupItem value="glinr" variant="glinr" aria-label="glinr" />
        <RadioGroupItem value="solid" variant="solid" aria-label="solid" />
        <RadioGroupItem value="plain" variant="plain" aria-label="plain" />
        <RadioGroupItem value="soft" variant="soft" aria-label="soft" />
        <RadioGroupItem value="outline" variant="outline" aria-label="outline" />
        <RadioGroupItem value="ghost" variant="ghost" aria-label="ghost" />
      </RadioGroup>
      <RadioGroup defaultValue="md" orientation="horizontal" className="flex items-center gap-3">
        <RadioGroupItem value="sm" size="sm" aria-label="Small" />
        <RadioGroupItem value="md" size="md" aria-label="Medium" />
        <RadioGroupItem value="lg" size="lg" aria-label="Large" />
      </RadioGroup>
    </div>
  )
}
```

### Glass (opt-in)

Glass is opt-in and needs a backdrop behind it: pick Photo or Vivid in the stage backdrop switcher.

```tsx
import { RadioGroup, RadioGroupItem } from "@glinui/ui"

export function Demo() {
  return (
    <RadioGroup defaultValue="a" orientation="horizontal" className="flex items-center gap-3">
      <RadioGroupItem value="a" variant="glass" aria-label="A" />
      <RadioGroupItem value="b" variant="glass" aria-label="B" />
    </RadioGroup>
  )
}
```

## Props

### RadioGroupItemProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled?` | `boolean` |  | Disables this radio item. |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Size of the radio control. |
| `value` | `string` |  | Value submitted by this radio item when selected. |
| `variant?` | `ControlVariantProp` |  | Surface treatment for the radio item shell. Omit to follow the ambient design style. Also: solid, plain, soft, outline, ghost, glass (opt... |

### RadioGroupProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultValue?` | `string` |  | Initial selected value for uncontrolled usage. |
| `disabled?` | `boolean` |  | Disables all radio items in the group. |
| `onValueChange?` | `(value: string) => void` |  | Called when the selected value changes. |
| `orientation?` | `"horizontal" \| "vertical"` |  | Layout direction for radio items. |
| `value?` | `string` |  | Controlled selected value. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Built on Radix RadioGroup with full ARIA support.
- Each item requires a unique `value`.
- Built on `@radix-ui/react-radio-group`, which follows the [WAI-ARIA Radio Group pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/).
- Arrow keys move focus and selection between items within the group.
- Each `RadioGroupItem` must have a corresponding `<label>` linked via `id` / `htmlFor`.
- The group can be given a label via `aria-label` or `aria-labelledby` on `RadioGroup`.

Keyboard:

| Key | Action |
| --- | --- |
| Arrow Up / Down / Left / Right | Navigate between radio items. |
| Space | Select the focused radio item. |

ARIA:

- `role="radiogroup"` on root
- `role="radio"` on items
- `aria-checked`

- Reduced motion: Indicator transitions respect `prefers-reduced-motion`. The fill indicator animation on selection is removed when `prefers-reduced-motion: reduce` is detected.

---

# Switch

> On/off control built on Radix switch primitive.

- id: `switch`
- type: primitive
- category: Forms and inputs
- tags: primitive
- docs: https://glinui.com/docs/components/radix/switch
- markdown: https://glinui.com/md/switch.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add switch
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/switch.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Switch, CONTROL_LEGACY_VARIANTS, CONTROL_SIZE_CLASSES, SWITCH_SIZES, SWITCH_MOTION, FILL_CLASS, THUMB_BG_CLASS, GlinProvider } from "@glinui/ui"
```

## Usage

A notification settings list where each switch is described by its note.

```tsx
import { Card, CardContent, CardDescription, CardHeader, CardTitle, Switch } from "@glinui/ui"

export function SwitchNotifications() {
  const items = [
    { id: "mentions", label: "Mentions and replies", note: "When someone tags you in a thread.", on: true },
    { id: "digest", label: "Weekly digest", note: "A Monday summary of what shipped.", on: true },
    { id: "deploys", label: "Deploy failures", note: "Immediate email when a build fails.", on: true },
    { id: "marketing", label: "Product news", note: "Occasional updates about new features.", on: false }
  ]
  return (
    <Card className="w-full max-w-lg">
      <CardHeader>
        <CardTitle>Email notifications</CardTitle>
        <CardDescription>Choose what lands in your inbox.</CardDescription>
      </CardHeader>
      <CardContent className="divide-y divide-border/60">
        {items.map((item) => (
          <div key={item.id} className="flex items-center justify-between gap-4 py-3 first:pt-0 last:pb-0">
            <div className="min-w-0">
              <label htmlFor={`sw-${item.id}`} className="block text-sm font-medium text-foreground">{item.label}</label>
              <p id={`sw-${item.id}-note`} className="text-sm text-[var(--color-muted)]">{item.note}</p>
            </div>
            <Switch id={`sw-${item.id}`} aria-describedby={`sw-${item.id}-note`} defaultChecked={item.on} />
          </div>
        ))}
      </CardContent>
    </Card>
  )
}
```

### State matrix

```tsx
import { Switch } from "@glinui/ui"

export function Demo() {
  return (
    <div className="grid grid-cols-3 gap-4">
      {(["sm", "md", "lg"] as const).map((size) => (
        <div key={size} className="flex flex-col items-center gap-3">
          <Switch aria-label="Off" size={size} />
          <Switch aria-label="On" size={size} defaultChecked />
          <Switch aria-label="Disabled" size={size} disabled />
          <Switch aria-label="Disabled on" size={size} disabled defaultChecked />
        </div>
      ))}
    </div>
  )
}
```

### Variants

Each variant on and off. Pick a backdrop in the stage to check contrast.

```tsx
import { Switch } from "@glinui/ui"

export function Demo() {
  return (
    <div className="flex flex-wrap items-center gap-4">
      <Switch variant="glinr" defaultChecked aria-label="glinr on" />
      <Switch variant="glinr" aria-label="glinr off" />
      <Switch variant="solid" defaultChecked aria-label="solid on" />
      <Switch variant="solid" aria-label="solid off" />
      <Switch variant="plain" defaultChecked aria-label="plain on" />
      <Switch variant="plain" aria-label="plain off" />
      <Switch variant="soft" defaultChecked aria-label="soft on" />
      <Switch variant="soft" aria-label="soft off" />
      <Switch variant="outline" defaultChecked aria-label="outline on" />
      <Switch variant="outline" aria-label="outline off" />
      <Switch variant="ghost" defaultChecked aria-label="ghost on" />
      <Switch variant="ghost" aria-label="ghost off" />
    </div>
  )
}
```

## Props

### SwitchProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `activeColor?` | `string` |  | Custom checked color (any CSS color). Applied as a CSS custom property, no inline style. |
| `checked?` | `boolean` |  | Controlled checked state. |
| `defaultChecked?` | `boolean` |  | Initial checked state for uncontrolled usage. |
| `description?` | `React.ReactNode` |  | Helper text under the label, linked through aria-describedby. |
| `disabled?` | `boolean` |  | Prevents interaction and applies muted styling. |
| `fieldClassName?` | `string` |  | Class applied to the label row wrapper (only when label or description is set). |
| `label?` | `React.ReactNode` |  | Field label. Renders a clickable label row. |
| `loading?` | `boolean` | `false` | Shows a spinner in the thumb, makes the switch inert and sets aria-busy. |
| `name?` | `string` |  | Form field name submitted with form data. |
| `offIcon?` | `React.ReactNode` |  | Icon shown inside the thumb when off (sized to the thumb). |
| `offLabel?` | `string` | `"Off"` | Text for the off state when `showLabels` is set. |
| `onCheckedChange?` | `(checked: boolean) => void` |  | Callback fired when the checked state changes. |
| `onIcon?` | `React.ReactNode` |  | Icon shown inside the thumb when on (sized to the thumb). |
| `onLabel?` | `string` | `"On"` | Text for the on state when `showLabels` is set. |
| `required?` | `boolean` |  | Marks the switch as required within a form. |
| `showLabels?` | `boolean` | `false` | Render "On"/"Off" text inside the track (large size only). |
| `size?` | `SwitchSize` | `"md"` | Track and thumb size: sm 36x20, md 44x24, lg 52x28. |
| `value?` | `string` |  | Value submitted with the form when checked. |
| `variant?` | `ControlVariantProp` |  | Track look. Omit to follow the ambient design style (glinr = inset well track with a raised accent fill). Also: solid, plain, soft, outli... |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Built on Radix Switch with `role="switch"`.
- `label` and `description` wire `htmlFor` and `aria-describedby` for you.
- 44px minimum hit area; the thumb travels toward the inline end in RTL.
- Built on `@radix-ui/react-switch` which renders a native `button` with `role="switch"`.
- Associates with a visible `label` via `htmlFor` / `id` pairing, or via `aria-label` when no visual label element is present.
- Keyboard togglable with `Space` and `Enter`.
- `aria-checked` is managed automatically by the primitive.

Keyboard:

| Key | Action |
| --- | --- |
| Space | Toggle the switch on/off. |

ARIA:

- `role="switch"`
- `aria-checked`
- `aria-busy` while loading

- Reduced motion: The thumb slide and stretch are instant under `prefers-reduced-motion` and when `data-glin-motion` is `none` or `subtle`. The thumb slide transition respects `prefers-reduced-motion` and removes the transform animation when enabled.

---

# Slider

> Range input control built on Radix slider primitive with glass thumb/track styling.

- id: `slider`
- type: primitive
- category: Forms and inputs
- tags: primitive
- docs: https://glinui.com/docs/components/radix/slider
- markdown: https://glinui.com/md/slider.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add slider
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/slider.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Slider, CONTROL_LEGACY_VARIANTS, CONTROL_SIZE_CLASSES, GlinProvider, GLIN_MOTIONS, GLIN_ENGINES, GLIN_SURFACES, GLIN_STYLES } from "@glinui/ui"
```

## Usage

A range slider with a live readout and a single volume slider.

```tsx
"use client"

import { useState } from "react"
import { Button, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Label, Slider } from "@glinui/ui"

export function SliderPriceFilter() {
  const [range, setRange] = useState([40, 220])
  const [volume, setVolume] = useState([65])
  const results = Math.max(0, Math.round((range[1] - range[0]) * 0.42))
  return (
    <Card className="w-full max-w-sm">
      <CardHeader>
        <CardTitle>Filter listings</CardTitle>
        <CardDescription>{results} stays match your budget.</CardDescription>
      </CardHeader>
      <CardContent className="grid gap-6">
        <div className="grid gap-3">
          <div className="flex items-baseline justify-between">
            <Label htmlFor="price-range">Price per night</Label>
            <output htmlFor="price-range" className="text-sm font-medium tabular-nums text-foreground">
              ${range[0]} to ${range[1]}
            </output>
          </div>
          <Slider id="price-range" value={range} onValueChange={setRange} min={0} max={400} step={10} aria-label="Price range" />
        </div>
        <div className="grid gap-3">
          <div className="flex items-baseline justify-between">
            <Label>Preview volume</Label>
            <span className="text-sm tabular-nums text-[var(--color-muted)]">{volume[0]}%</span>
          </div>
          <Slider value={volume} onValueChange={setVolume} max={100} step={1} aria-label="Preview volume" />
        </div>
      </CardContent>
      <CardFooter className="flex justify-between">
        <Button variant="ghost" onClick={() => { setRange([40, 220]); setVolume([65]) }}>Reset</Button>
        <Button variant="solid" tone="accent">Show {results} stays</Button>
      </CardFooter>
    </Card>
  )
}
```

### Variants

```tsx
import { Slider } from "@glinui/ui"

export function Demo() {
  return (
    <div className="space-y-4">
      <Slider variant="glinr" defaultValue={[20]} aria-label="glinr slider" />
      <Slider variant="solid" defaultValue={[32]} aria-label="solid slider" />
      <Slider variant="plain" defaultValue={[44]} aria-label="plain slider" />
      <Slider variant="soft" defaultValue={[56]} aria-label="soft slider" />
      <Slider variant="outline" defaultValue={[68]} aria-label="outline slider" />
      <Slider variant="ghost" defaultValue={[80]} aria-label="ghost slider" />
    </div>
  )
}
```

### Sizes

```tsx
import { Slider } from "@glinui/ui"

export function Demo() {
  return (
    <div className="space-y-4">
      <Slider size="sm" defaultValue={[24]} aria-label="Small slider" />
      <Slider size="md" defaultValue={[52]} aria-label="Medium slider" />
      <Slider size="lg" defaultValue={[78]} aria-label="Large slider" />
    </div>
  )
}
```

## Props

### SliderProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from sliderVariants. |
| `variant?` | `ControlVariantProp` |  | Surface look. Omit to follow the ambient design style (glinr = inset track, accent range, raised key thumb). Also: solid, plain, soft, ou... |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Built on Radix Slider with full ARIA support.
- Supports single-value and range sliders (multiple thumbs).
- Provide `aria-label` for screen readers.
- Thumb includes visible focus ring.
- Provide `aria-label` for each slider input.

Keyboard:

| Key | Action |
| --- | --- |
| Arrow Left / Right | Decrease / increase value by one step. |
| Home | Set to minimum value. |
| End | Set to maximum value. |

ARIA:

- `role="slider"`
- `aria-valuenow`
- `aria-valuemin`
- `aria-valuemax`
- `aria-orientation`

- Reduced motion: Thumb and track transitions respect `prefers-reduced-motion`.

---

# Modal / Dialog

> Layered dialog for focused tasks or confirmations.

- id: `modal`
- type: primitive
- category: Overlays and menus
- tags: primitive
- docs: https://glinui.com/docs/components/radix/modal
- markdown: https://glinui.com/md/modal.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add modal
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/modal.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Modal, ModalTrigger, ModalClose, ModalPortal, ModalOverlay, ModalContent, ModalHeader, ModalFooter } from "@glinui/ui"
```

## Usage

Overlay demos on this page render inside the preview stage so they stay contained. In your app they portal to the document body as usual.

A members card with an invite dialog that holds a form and a live list. Overlays portal into the preview stage here. In your app they render into the page.

```tsx
"use client"

import * as React from "react"
import { UserPlus } from "@phosphor-icons/react"
import {
  Avatar,
  Badge,
  Button,
  Heading,
  Input,
  Label,
  Modal,
  ModalClose,
  ModalContent,
  ModalDescription,
  ModalFooter,
  ModalHeader,
  ModalTitle,
  ModalTrigger,
  Text
} from "@glinui/ui"

const CARD = "mx-auto w-full rounded-2xl border border-[var(--line-soft)] bg-[var(--surface-1)] p-5 [box-shadow:var(--elev-1)]"

const MEMBERS = [
  { name: "Ava Kim", mail: "ava@lumen.test", role: "Owner", initials: "AK" },
  { name: "Jon Reyes", mail: "jon@lumen.test", role: "Admin", initials: "JR" },
  { name: "Sara Patel", mail: "sara@lumen.test", role: "Editor", initials: "SP" }
]

export function ModalInviteHero() {
  const [emails, setEmails] = React.useState<string[]>(["mia@lumen.test"])
  const [draft, setDraft] = React.useState("")
  const add = () => {
    const value = draft.trim()
    if (value && !emails.includes(value)) setEmails([...emails, value])
    setDraft("")
  }
  return (
    <div className={`${CARD} max-w-lg`}>
      <div className="flex items-center justify-between gap-3">
        <div>
          <Heading level={3} size="sm">Members</Heading>
          <Text size="sm" className="text-[var(--color-muted)]">3 of 10 seats used</Text>
        </div>
        <Modal>
          <ModalTrigger asChild><Button size="sm"><UserPlus aria-hidden="true" />Invite teammates</Button></ModalTrigger>
          <ModalContent>
            <ModalHeader>
              <ModalTitle>Invite teammates</ModalTitle>
              <ModalDescription>They get an email with a link to join Lumen.</ModalDescription>
            </ModalHeader>
            <form
              className="grid gap-3"
              onSubmit={(event) => {
                event.preventDefault()
                add()
              }}
            >
              <Label htmlFor="invite-email">Email address</Label>
              <div className="flex gap-2">
                <Input id="invite-email" type="email" placeholder="name@company.com" value={draft} onChange={(event) => setDraft(event.target.value)} />
                <Button type="submit" variant="outline">Add</Button>
              </div>
            </form>
            <ul className="grid gap-2" aria-label="People to invite">
              {emails.map((email) => (
                <li key={email} className="flex items-center justify-between gap-3 text-sm">
                  <span className="flex items-center gap-2"><Avatar size="xs" fallback={email.slice(0, 2).toUpperCase()} alt="" />{email}</span>
                  <Badge size="sm">Editor</Badge>
                </li>
              ))}
            </ul>
            <ModalFooter>
              <ModalClose asChild><Button variant="ghost">Cancel</Button></ModalClose>
              <ModalClose asChild><Button disabled={emails.length === 0}>{`Send ${emails.length} invite${emails.length === 1 ? "" : "s"}`}</Button></ModalClose>
            </ModalFooter>
          </ModalContent>
        </Modal>
      </div>
      <ul className="mt-4 grid divide-y divide-[var(--line-soft)]">
        {MEMBERS.map((member) => (
          <li key={member.mail} className="flex items-center gap-3 py-2.5">
            <Avatar size="sm" fallback={member.initials} alt="" />
            <span className="grid min-w-0 flex-1 text-sm">
              <span className="font-medium">{member.name}</span>
              <span className="truncate text-xs text-[var(--color-muted)]">{member.mail}</span>
            </span>
            <Badge size="sm">{member.role}</Badge>
          </li>
        ))}
      </ul>
    </div>
  )
}
```

### Sizes

Choose sm, md or lg to match the amount of content.

```tsx
"use client"

import {
  Button,
  Input,
  Modal,
  ModalClose,
  ModalContent,
  ModalDescription,
  ModalFooter,
  ModalHeader,
  ModalTitle,
  ModalTrigger
} from "@glinui/ui"

export function ModalSizesExample() {
  return (
    <div className="mx-auto flex flex-wrap items-center justify-center gap-3">
      {(["sm", "md", "lg"] as const).map((size) => (
        <Modal key={size}>
          <ModalTrigger asChild><Button variant="outline" size="sm">{`Size ${size}`}</Button></ModalTrigger>
          <ModalContent size={size}>
            <ModalHeader>
              <ModalTitle>Rename workspace</ModalTitle>
              <ModalDescription>Pick a name your team will recognise.</ModalDescription>
            </ModalHeader>
            <Input aria-label="Workspace name" defaultValue="Lumen" />
            <ModalFooter>
              <ModalClose asChild><Button variant="ghost">Cancel</Button></ModalClose>
              <ModalClose asChild><Button>Save name</Button></ModalClose>
            </ModalFooter>
          </ModalContent>
        </Modal>
      ))}
    </div>
  )
}
```

### Glass (opt-in)

variant="glass" is opt-in. It blurs and tints whatever sits behind the panel, so it needs a colourful or photographic backdrop: switch the stage backdrop to see it.

```tsx
import { Button, Modal, ModalClose, ModalContent, ModalDescription, ModalFooter, ModalHeader, ModalTitle, ModalTrigger } from "@glinui/ui"

export function Demo() {
  return (
    <Modal>
      <ModalTrigger asChild><Button variant="outline">Open glass modal</Button></ModalTrigger>
      <ModalContent variant="glass">
        <ModalHeader>
          <ModalTitle>Share workspace</ModalTitle>
          <ModalDescription>The page behind stays visible through the panel.</ModalDescription>
        </ModalHeader>
        <ModalFooter>
          <ModalClose asChild><Button variant="ghost">Cancel</Button></ModalClose>
          <Button>Share</Button>
        </ModalFooter>
      </ModalContent>
    </Modal>
  )
}
```

## Props

### ModalContentProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `container?` | `HTMLElement \| null` |  | Element to portal into. When set, overlay and content use absolute positioning scoped to the nearest positioned ancestor. |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from modalSizeVariants. |
| `variant?` | `PanelVariantProp` |  | Surface look. Omit for the ambient design style (glinr by default). `glass` is opt-in and needs a colourful or photographic backdrop to r... |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Built on Radix Dialog with focus trapping.
- ModalTitle is required for screen readers.
- Background interaction blocked when modal.
- Focus is trapped inside the dialog while open.
- `Escape` closes the dialog and returns focus to the trigger.
- The backdrop overlay blocks interaction with background content.

Keyboard:

| Key | Action |
| --- | --- |
| Escape | Close the modal. |
| Tab | Cycle focus within the modal. |

ARIA:

- `role="dialog"`
- `aria-modal="true"`
- `aria-labelledby`
- `aria-describedby`

- Reduced motion: Open/close transitions respect `prefers-reduced-motion`. The overlay fade and content scale animations respect `prefers-reduced-motion` and collapse to instant transitions.

---

# Alert Dialog

> Destructive action confirmation dialog with explicit cancel and action controls.

- id: `alert-dialog`
- type: primitive
- category: Overlays and menus
- tags: primitive
- docs: https://glinui.com/docs/components/radix/alert-dialog
- markdown: https://glinui.com/md/alert-dialog.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add alert-dialog
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/alert-dialog.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { AlertDialog, AlertDialogTrigger, AlertDialogPortal, AlertDialogOverlay, AlertDialogContent, AlertDialogHeader, AlertDialogFooter, AlertDialogTitle } from "@glinui/ui"
```

## Usage

Overlay demos on this page render inside the preview stage so they stay contained. In your app they portal to the document body as usual.

A destructive confirmation that lists consequences and asks for the project name before the action unlocks. Overlays portal into the preview stage here. In your app they render into the page.

```tsx
"use client"

import * as React from "react"
import { Trash } from "@phosphor-icons/react"
import {
  AlertDialog,
  AlertDialogAction,
  AlertDialogCancel,
  AlertDialogContent,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogTitle,
  AlertDialogTrigger,
  Button,
  Heading,
  IconFrame,
  Input,
  Label,
  Text
} from "@glinui/ui"

const CARD = "mx-auto w-full rounded-2xl border border-[var(--line-soft)] bg-[var(--surface-1)] p-5 [box-shadow:var(--elev-1)]"

export function AlertDeleteHero() {
  const [confirm, setConfirm] = React.useState("")
  return (
    <div className={`${CARD} max-w-lg`}>
      <div className="flex items-start gap-3">
        <IconFrame tone="danger"><Trash aria-hidden="true" /></IconFrame>
        <div className="grid flex-1 gap-1">
          <Heading level={3} size="sm">Delete this project</Heading>
          <Text size="sm" className="text-[var(--color-muted)]">Removes lumen-web, its deployments and all stored analytics.</Text>
        </div>
      </div>
      <div className="mt-4 flex justify-end">
        <AlertDialog onOpenChange={() => setConfirm("")}>
          <AlertDialogTrigger asChild><Button variant="outline" tone="danger">Delete project</Button></AlertDialogTrigger>
          <AlertDialogContent>
            <AlertDialogHeader>
              <AlertDialogTitle>Delete lumen-web?</AlertDialogTitle>
              <AlertDialogDescription>This cannot be undone. Deleting the project will:</AlertDialogDescription>
            </AlertDialogHeader>
            <ul className="list-disc space-y-1 ps-5 text-sm text-[var(--color-muted)]">
              <li>Remove 142 deployments and their logs</li>
              <li>Disconnect 3 custom domains</li>
              <li>Cancel the 2 scheduled jobs</li>
            </ul>
            <div className="grid gap-2">
              <Label htmlFor="confirm-name">Type lumen-web to confirm</Label>
              <Input id="confirm-name" value={confirm} onChange={(event) => setConfirm(event.target.value)} autoComplete="off" />
            </div>
            <AlertDialogFooter>
              <AlertDialogCancel>Keep project</AlertDialogCancel>
              <AlertDialogAction variant="destructive" disabled={confirm !== "lumen-web"}>Delete project</AlertDialogAction>
            </AlertDialogFooter>
          </AlertDialogContent>
        </AlertDialog>
      </div>
    </div>
  )
}
```

### Discard draft

A small alert dialog for a reversible but lossy action.

```tsx
"use client"

import {
  AlertDialog,
  AlertDialogAction,
  AlertDialogCancel,
  AlertDialogContent,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogTitle,
  AlertDialogTrigger,
  Button,
  Input,
  Label
} from "@glinui/ui"

const CARD = "mx-auto w-full rounded-2xl border border-[var(--line-soft)] bg-[var(--surface-1)] p-5 [box-shadow:var(--elev-1)]"

export function AlertDiscardExample() {
  return (
    <div className={`${CARD} max-w-md`}>
      <Label htmlFor="draft-title">Post title</Label>
      <Input id="draft-title" className="mt-2" defaultValue="Launch notes for v2.4" />
      <div className="mt-4 flex justify-end gap-2">
        <AlertDialog>
          <AlertDialogTrigger asChild><Button variant="ghost">Discard draft</Button></AlertDialogTrigger>
          <AlertDialogContent size="sm">
            <AlertDialogHeader>
              <AlertDialogTitle>Discard this draft?</AlertDialogTitle>
              <AlertDialogDescription>Your unsaved edits will be lost.</AlertDialogDescription>
            </AlertDialogHeader>
            <AlertDialogFooter>
              <AlertDialogCancel>Keep editing</AlertDialogCancel>
              <AlertDialogAction>Discard</AlertDialogAction>
            </AlertDialogFooter>
          </AlertDialogContent>
        </AlertDialog>
        <Button>Publish</Button>
      </div>
    </div>
  )
}
```

### Glass (opt-in)

Glass is opt-in and needs a colourful or photographic backdrop to read as frosted. Pick one in the stage header.

```tsx
import {
  AlertDialog,
  AlertDialogAction,
  AlertDialogCancel,
  AlertDialogContent,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogTitle,
  AlertDialogTrigger,
  Button
} from "@glinui/ui"

export function Demo() {
  return (
    <AlertDialog>
      <AlertDialogTrigger asChild>
        <Button variant="outline">Archive workspace</Button>
      </AlertDialogTrigger>
      <AlertDialogContent variant="glass" size="sm">
        <AlertDialogHeader>
          <AlertDialogTitle>Archive workspace?</AlertDialogTitle>
          <AlertDialogDescription>
            Members will lose write access until you restore the workspace.
          </AlertDialogDescription>
        </AlertDialogHeader>
        <AlertDialogFooter>
          <AlertDialogCancel>Not now</AlertDialogCancel>
          <AlertDialogAction variant="glass">Archive</AlertDialogAction>
        </AlertDialogFooter>
      </AlertDialogContent>
    </AlertDialog>
  )
}
```

## Props

### AlertDialogActionProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant?` | `"default" \| "destructive" \| "glass" \| "matte"` | `"default"` | Variant option from alertDialogActionVariants. |

### AlertDialogContentProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `container?` | `HTMLElement \| null` |  | Element to portal into. When set, overlay and content use absolute positioning scoped to the nearest positioned ancestor. |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from alertDialogSizeVariants. |
| `variant?` | `PanelVariantProp` |  | Surface look. Omit for the ambient design style (glinr by default). `glass` is opt-in and needs a rich backdrop. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`, `destructive`, `glass`, `matte`.

## Accessibility

- Built on Radix Alert Dialog with focus trap and screen reader semantics.
- Use a clear, explicit `AlertDialogTitle` and concise `AlertDialogDescription` for destructive actions.
- Focus returns to the trigger after close.
- Uses `role="alertdialog"` semantics through Radix.
- Focus is trapped inside the dialog while open.
- Keep destructive copy explicit in `AlertDialogTitle` and `AlertDialogDescription`.

Keyboard:

| Key | Action |
| --- | --- |
| Escape | Close the alert dialog. |
| Tab / Shift+Tab | Cycle focus between actions. |
| Enter / Space | Activate focused action. |

ARIA:

- `role="alertdialog"`
- `aria-labelledby`
- `aria-describedby`

- Reduced motion: Overlay and panel transitions respect `prefers-reduced-motion` and reduce to instant state changes.

---

# Sheet / Drawer

> Sliding panel for side, top, or bottom contextual workflows.

- id: `sheet`
- type: primitive
- category: Overlays and menus
- tags: primitive
- docs: https://glinui.com/docs/components/radix/sheet
- markdown: https://glinui.com/md/sheet.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add sheet
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/sheet.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Sheet, Drawer, SheetTrigger, SheetClose, SheetPortal, SheetOverlay, SheetContent, SheetHeader } from "@glinui/ui"
```

## Usage

Overlay demos on this page render inside the preview stage so they stay contained. In your app they portal to the document body as usual.

A right-hand panel with form controls, opened from a results list. Overlays portal into the preview stage here. In your app they render into the page.

```tsx
"use client"

import { Funnel } from "@phosphor-icons/react"
import {
  Badge,
  Button,
  Checkbox,
  Heading,
  Label,
  Sheet,
  SheetClose,
  SheetContent,
  SheetDescription,
  SheetFooter,
  SheetHeader,
  SheetTitle,
  SheetTrigger,
  Switch
} from "@glinui/ui"

const CARD = "mx-auto w-full rounded-2xl border border-[var(--line-soft)] bg-[var(--surface-1)] p-5 [box-shadow:var(--elev-1)]"

const LISTINGS = [
  { name: "Harbor loft", meta: "2 bed, 1 bath", price: "$2,400" },
  { name: "Maple row house", meta: "3 bed, 2 bath", price: "$3,150" },
  { name: "Station studio", meta: "Studio, 1 bath", price: "$1,350" }
]

export function SheetFiltersHero() {
  return (
    <div className={`${CARD} max-w-lg`}>
      <div className="flex items-center justify-between gap-3">
        <Heading level={3} size="sm">Rentals near you</Heading>
        <Sheet>
          <SheetTrigger asChild><Button size="sm" variant="outline"><Funnel aria-hidden="true" />Filters<Badge size="sm" className="ms-1">2</Badge></Button></SheetTrigger>
          <SheetContent side="right">
            <SheetHeader>
              <SheetTitle>Filters</SheetTitle>
              <SheetDescription>Narrow 128 listings by what matters.</SheetDescription>
            </SheetHeader>
            <fieldset className="grid gap-3 py-4">
              <legend className="mb-1 text-sm font-medium">Bedrooms</legend>
              {["Studio", "1 bedroom", "2 bedrooms", "3 or more"].map((label, index) => (
                <label key={label} className="flex items-center gap-2 text-sm"><Checkbox defaultChecked={index === 2} />{label}</label>
              ))}
            </fieldset>
            <div className="flex items-center justify-between gap-3 border-t border-[var(--line-soft)] py-3 text-sm">
              <Label htmlFor="pets">Pets allowed</Label>
              <Switch id="pets" defaultChecked />
            </div>
            <SheetFooter>
              <SheetClose asChild><Button variant="ghost">Reset</Button></SheetClose>
              <SheetClose asChild><Button>Show 41 results</Button></SheetClose>
            </SheetFooter>
          </SheetContent>
        </Sheet>
      </div>
      <ul className="mt-4 grid divide-y divide-[var(--line-soft)]">
        {LISTINGS.map((item) => (
          <li key={item.name} className="flex items-center justify-between gap-3 py-3 text-sm">
            <span className="grid"><span className="font-medium">{item.name}</span><span className="text-xs text-[var(--color-muted)]">{item.meta}</span></span>
            <span className="tabular-nums">{item.price}</span>
          </li>
        ))}
      </ul>
    </div>
  )
}
```

### Mobile navigation

A left sheet used as a mobile nav drawer.

```tsx
"use client"

import { FolderSimple, GearSix, House, List, Users } from "@phosphor-icons/react"
import {
  Button,
  Sheet,
  SheetContent,
  SheetDescription,
  SheetHeader,
  SheetTitle,
  SheetTrigger,
  Text
} from "@glinui/ui"

export function SheetMobileNavExample() {
  const links = [
    { icon: House, label: "Home" },
    { icon: FolderSimple, label: "Projects" },
    { icon: Users, label: "Team" },
    { icon: GearSix, label: "Settings" }
  ]
  return (
    <div className="mx-auto w-full max-w-sm rounded-2xl border border-[var(--line-soft)] bg-[var(--surface-1)] [box-shadow:var(--elev-1)]">
      <div className="flex items-center gap-2 border-b border-[var(--line-soft)] px-3 py-2">
        <Sheet>
          <SheetTrigger asChild><Button size="icon" variant="ghost" aria-label="Open menu"><List aria-hidden="true" /></Button></SheetTrigger>
          <SheetContent side="left">
            <SheetHeader>
              <SheetTitle>Lumen</SheetTitle>
              <SheetDescription>Jump to a section.</SheetDescription>
            </SheetHeader>
            <nav aria-label="Mobile" className="grid gap-1 py-4">
              {links.map(({ icon: Icon, label }) => (
                <a key={label} href="#" className="flex items-center gap-3 rounded-lg px-3 py-2 text-sm hover:bg-[color-mix(in_oklab,var(--color-foreground)_8%,transparent)]"><Icon aria-hidden="true" className="size-4" />{label}</a>
              ))}
            </nav>
          </SheetContent>
        </Sheet>
        <span className="text-sm font-semibold">Lumen</span>
      </div>
      <div className="p-4"><Text size="sm" className="text-[var(--color-muted)]">Tap the menu to slide the navigation in from the left.</Text></div>
    </div>
  )
}
```

### Bottom Sheet

```tsx
import { Sheet, SheetTrigger, SheetContent, SheetHeader, SheetTitle, Button } from "@glinui/ui"

export function Demo() {
  return (
    <Sheet>
      <SheetTrigger asChild><Button>Bottom Sheet</Button></SheetTrigger>
      <SheetContent side="bottom">
        <SheetHeader><SheetTitle>Quick Actions</SheetTitle></SheetHeader>
      </SheetContent>
    </Sheet>
  )
}
```

## Props

### SheetContentProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `container?` | `HTMLElement \| null` |  | Element to portal into. When set, overlay and content use absolute positioning scoped to the nearest positioned ancestor. |
| `side?` | `"top" \| "bottom" \| "left" \| "right"` | `"right"` | Variant option from sheetContentVariants. |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from sheetContentVariants. |
| `variant?` | `PanelVariantProp` |  | Surface look. Omit for the ambient design style (glinr by default). `glass` is opt-in and needs a rich backdrop. |

### SheetTriggerProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from sheetTriggerVariants. |
| `variant?` | `"default" \| "glass" \| "frosted" \| "outline" \| "ghost"` | `"default"` | Variant option from sheetTriggerVariants. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`, `glass`, `frosted`, `outline`, `ghost`.

## Accessibility

- Built on Radix Dialog with focus trapping.
- SheetTitle required for screen readers.
- Focus is trapped while open and restored on close.

Keyboard:

| Key | Action |
| --- | --- |
| Escape | Close the sheet. |
| Tab | Cycle focus within the sheet. |

ARIA:

- `role="dialog"`
- `aria-modal="true"`
- `aria-labelledby`

- Reduced motion: Slide transitions respect `prefers-reduced-motion`.

---

# Floating Panel

> Draggable glass panel with depth shadows and optional close button.

- id: `floating-panel`
- type: signature
- category: Overlays and menus
- tags: signature
- docs: https://glinui.com/docs/components/floating-panel
- markdown: https://glinui.com/md/floating-panel.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add floating-panel
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/floating-panel.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { FloatingPanel } from "@glinui/ui"
```

## Usage

```tsx
import { FloatingPanel } from "@glinui/ui"

// Omit variant to follow the ambient style (glinr by default).
export function FloatingPanelVariants() {
  return (
    <>
      <FloatingPanel variant="glinr">
        ...
      </FloatingPanel>
      <FloatingPanel variant="plain">
        ...
      </FloatingPanel>
      <FloatingPanel variant="solid">
        ...
      </FloatingPanel>
      <FloatingPanel variant="glass">
        ...
      </FloatingPanel>
    </>
  )
}
```

```tsx
import { FloatingPanel } from "@glinui/ui"

export function FloatingPanelTones() {
  return (
    <FloatingPanel variant="soft" tone="success">
      ...
    </FloatingPanel>
  )
}
```

```tsx
// Panels rendered statically (className="static") inside a dashboard row.
import { FloatingPanel } from "@glinui/ui"

export function FloatingPanelLayout() {
  return (
    <section className="grid gap-4 sm:grid-cols-3">
      ...
    </section>
  )
}
```

## Props

### FloatingPanelProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `closable?` | `boolean` | `false` | Show close button |
| `defaultX?` | `number` | `0` | Initial x position |
| `defaultY?` | `number` | `0` | Initial y position |
| `draggable?` | `boolean` | `true` | Enable dragging |
| `onClose?` | `() => void` |  | Close callback |
| `width?` | `number \| string` | `320` | Panel width |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Close button has `aria-label="Close panel"`.
- Drag interaction uses Pointer Events API for broad device support.
- Interactive elements inside the panel (buttons, links) are not affected by drag.
- Reduced motion: No animation is used, drag is position-based, not animated.

---

# Popover

> Floating content panel anchored to a trigger element.

- id: `popover`
- type: primitive
- category: Overlays and menus
- tags: primitive
- docs: https://glinui.com/docs/components/radix/popover
- markdown: https://glinui.com/md/popover.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add popover
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/popover.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Popover, PopoverTrigger, PopoverContent, PopoverClose, PopoverAnchor, PANEL_ITEM, PANEL_ITEM_SELECTABLE, PANEL_SEPARATOR } from "@glinui/ui"
```

## Usage

A share popover opened by default with a link field and a switch. It stays interactive; press Escape to close.

```tsx
"use client"

import { Copy, FileText, Link as LinkIcon } from "@phosphor-icons/react"
import {
  Button,
  Input,
  Label,
  Popover,
  PopoverContent,
  PopoverTrigger,
  Switch
} from "@glinui/ui"

const CARD = "mx-auto w-full rounded-2xl border border-[var(--line-soft)] bg-[var(--surface-1)] p-5 [box-shadow:var(--elev-1)]"

export function PopoverShareHero() {
  return (
    <div className="mx-auto flex min-h-72 w-full max-w-md flex-col items-end">
      <div className={`${CARD} flex items-center justify-between gap-3`}>
        <span className="flex items-center gap-2 text-sm font-medium"><FileText aria-hidden="true" className="size-4" />Q4 roadmap</span>
        <Popover defaultOpen>
          <PopoverTrigger asChild><Button size="sm"><LinkIcon aria-hidden="true" />Share</Button></PopoverTrigger>
          <PopoverContent align="end" className="w-80" onOpenAutoFocus={(event) => event.preventDefault()}>
            <div className="grid gap-3">
              <div>
                <p className="text-sm font-medium">Share this document</p>
                <p className="text-xs text-[var(--color-muted)]">Anyone with the link can view.</p>
              </div>
              <div className="flex gap-2">
                <Input aria-label="Share link" readOnly value="lumen.test/d/q4-roadmap" />
                <Button size="icon" variant="outline" aria-label="Copy link"><Copy aria-hidden="true" /></Button>
              </div>
              <div className="flex items-center justify-between text-sm">
                <Label htmlFor="allow-comments">Allow comments</Label>
                <Switch id="allow-comments" defaultChecked />
              </div>
            </div>
          </PopoverContent>
        </Popover>
      </div>
    </div>
  )
}
```

### Notifications

A compact list in a popover anchored to an icon button.

```tsx
"use client"

import { Bell } from "@phosphor-icons/react"
import {
  Button,
  Popover,
  PopoverContent,
  PopoverTrigger
} from "@glinui/ui"

export function PopoverNotificationsExample() {
  const items = [
    { title: "Deploy finished", when: "2 min ago" },
    { title: "Sara commented on Pricing", when: "1 h ago" },
    { title: "Invoice INV-1042 paid", when: "Yesterday" }
  ]
  return (
    <div className="mx-auto flex w-full max-w-xs justify-center">
      <Popover>
        <PopoverTrigger asChild><Button variant="outline" size="icon" aria-label="Notifications, 3 new"><Bell aria-hidden="true" /></Button></PopoverTrigger>
        <PopoverContent className="w-72">
          <p className="text-sm font-medium">Notifications</p>
          <ul className="mt-2 grid divide-y divide-[var(--line-soft)]">
            {items.map((item) => (
              <li key={item.title} className="py-2 text-sm"><p>{item.title}</p><p className="text-xs text-[var(--color-muted)]">{item.when}</p></li>
            ))}
          </ul>
        </PopoverContent>
      </Popover>
    </div>
  )
}
```

### Glass (opt-in)

variant="glass" is opt-in. It blurs and tints what sits behind the panel (with a readable opacity floor), so it needs a colourful or photographic backdrop: switch the stage backdrop to see it.

```tsx
import { Button, Popover, PopoverContent, PopoverTrigger } from "@glinui/ui"

export function Demo() {
  return (
    <Popover>
      <PopoverTrigger asChild><Button variant="outline">Open glass popover</Button></PopoverTrigger>
      <PopoverContent variant="glass">Frosted, with a readable floor.</PopoverContent>
    </Popover>
  )
}
```

## Props

### PopoverContentProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `container?` | `HTMLElement \| null` |  | Element to portal into. Defaults to document.body. |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from popoverContentVariants. |
| `variant?` | `PanelVariantProp` |  | Surface look. Omit for the ambient design style (glinr by default). `glass` is opt-in and needs a rich backdrop. |

### PopoverTriggerProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from popoverTriggerVariants. |
| `variant?` | `"default" \| "glass" \| "frosted" \| "outline" \| "ghost"` | `"default"` | Variant option from popoverTriggerVariants. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`, `glass`, `frosted`, `outline`, `ghost`.

## Accessibility

- Built on Radix Popover with focus management.
- Focus returns to trigger on close.
- Keep popover content concise and task-focused.

Keyboard:

| Key | Action |
| --- | --- |
| Escape | Close the popover. |
| Tab | Cycle focus within the popover. |

ARIA:

- `aria-expanded` on trigger
- `aria-controls` linking trigger to content

- Reduced motion: Open/close transitions respect `prefers-reduced-motion`. Popover remains functional and readable with reduced motion settings.

---

# Hover Card

> Preview card that appears on hover or focus with configurable delays and placement.

- id: `hover-card`
- type: primitive
- category: Overlays and menus
- tags: primitive
- docs: https://glinui.com/docs/components/radix/hover-card
- markdown: https://glinui.com/md/hover-card.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add hover-card
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/hover-card.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { HoverCard, HoverCardTrigger, HoverCardContent, PANEL_ITEM, PANEL_ITEM_SELECTABLE, PANEL_SEPARATOR, PANEL_MOTION, PanelVariantProvider } from "@glinui/ui"
```

## Usage

A profile card shown from a handle. It is open by default here; in your app it opens on hover or keyboard focus.

```tsx
"use client"

import {
  Avatar,
  HoverCard,
  HoverCardContent,
  HoverCardTrigger
} from "@glinui/ui"

const CARD = "mx-auto w-full rounded-2xl border border-[var(--line-soft)] bg-[var(--surface-1)] p-5 [box-shadow:var(--elev-1)]"

export function HoverCardProfileHero() {
  return (
    <div className={`${CARD} max-w-md`}>
      <p className="text-sm leading-6">
        Release notes drafted by{" "}
        <HoverCard defaultOpen openDelay={100}>
          <HoverCardTrigger asChild>
            <a href="#" className="font-medium text-[var(--color-accent)] underline decoration-dotted underline-offset-4">@avakim</a>
          </HoverCardTrigger>
          <HoverCardContent className="w-80">
            <div className="flex gap-3">
              <Avatar size="lg" fallback="AK" alt="Ava Kim" />
              <div className="grid gap-1">
                <p className="text-sm font-semibold">Ava Kim</p>
                <p className="text-xs text-[var(--color-muted)]">@avakim</p>
                <p className="text-sm">Design engineer on the platform team. Writes about tokens and motion.</p>
                <div className="mt-1 flex items-center gap-3 text-xs text-[var(--color-muted)]">
                  <span><strong className="text-[var(--color-foreground)]">128</strong> posts</span>
                  <span><strong className="text-[var(--color-foreground)]">2.4k</strong> followers</span>
                </div>
              </div>
            </div>
          </HoverCardContent>
        </HoverCard>
        {" "}and reviewed by the docs team. Hover the handle to see who wrote it.
      </p>
    </div>
  )
}
```

### Link preview

A small card previewing the target of an inline link.

```tsx
"use client"

import {
  HoverCard,
  HoverCardContent,
  HoverCardTrigger
} from "@glinui/ui"

export function HoverCardLinkExample() {
  return (
    <div className="mx-auto w-full max-w-md text-sm leading-6">
      See the{" "}
      <HoverCard openDelay={100} closeDelay={80}>
        <HoverCardTrigger asChild><a href="#" className="font-medium underline decoration-dotted underline-offset-4">pricing page</a></HoverCardTrigger>
        <HoverCardContent className="w-72" size="sm">
          <p className="text-sm font-medium">Pricing</p>
          <p className="mt-1 text-xs text-[var(--color-muted)]">Free for individuals. Team plans start at $20 per seat each month.</p>
        </HoverCardContent>
      </HoverCard>{" "}
      for plan details.
    </div>
  )
}
```

### Delays and surface

```tsx
import { Badge, HoverCard, HoverCardContent, HoverCardTrigger } from "@glinui/ui"

export function Demo() {
  return (
    <div className="flex flex-wrap items-center gap-4">
      <HoverCard openDelay={0} closeDelay={150}>
        <HoverCardTrigger asChild>
          <button className="text-sm font-medium underline decoration-dotted underline-offset-4">
            Instant preview
          </button>
        </HoverCardTrigger>
        <HoverCardContent size="sm">
          <div className="space-y-2">
            <Badge>default</Badge>
            <p className="text-xs text-neutral-600 dark:text-neutral-300">Open delay: 0ms</p>
          </div>
        </HoverCardContent>
      </HoverCard>
      <HoverCard openDelay={500} closeDelay={250}>
        <HoverCardTrigger asChild>
          <button className="text-sm font-medium underline decoration-dotted underline-offset-4">
            Delayed preview
          </button>
        </HoverCardTrigger>
        <HoverCardContent variant="plain" size="md">
          <p className="text-xs text-neutral-600 dark:text-neutral-300">
            Opens after 500ms with the plain surface.
          </p>
        </HoverCardContent>
      </HoverCard>
    </div>
  )
}
```

## Props

### HoverCardContentProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `container?` | `HTMLElement \| null` |  | Element to portal into. Defaults to document.body. |
| `side?` | `"top" \| "right" \| "bottom" \| "left"` |  | Preferred side for the hover card. |
| `sideOffset?` | `number` | `10` | Gap in px between trigger and content. |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from hoverCardContentVariants. |
| `variant?` | `PanelVariantProp` |  | Surface look. Omit for the ambient design style (glinr by default). `glass` is opt-in and needs a rich backdrop. |

### HoverCardProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `closeDelay?` | `number` | `100` | Delay in ms before closing when pointer leaves. |
| `openDelay?` | `number` | `200` | Delay in ms before opening on pointer/focus. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Built on Radix Hover Card and opens on hover and keyboard focus.
- Hover card content should be supplemental; avoid critical-only information.
- Use non-interactive preview content for concise summaries.
- Use concise supplemental content, not primary actions.
- Keep the trigger semantic and focusable (`button`, `a`, etc.).
- For interactive panels, prefer `Popover`.

Keyboard:

| Key | Action |
| --- | --- |
| Tab / Shift+Tab | Move focus to or away from the trigger. |
| Escape | Close the hover card when focused. |

ARIA:

- `aria-describedby` linkage is handled by Radix primitives
- Trigger remains semantic and keyboard reachable

- Reduced motion: Entrance and exit transitions are disabled under `prefers-reduced-motion`.

---

# Tooltip

> Context hint on hover/focus using Radix tooltip primitive.

- id: `tooltip`
- type: primitive
- category: Overlays and menus
- tags: primitive
- docs: https://glinui.com/docs/components/radix/tooltip
- markdown: https://glinui.com/md/tooltip.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add tooltip
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/tooltip.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { TooltipProvider, Tooltip, TooltipTrigger, TooltipContent, PANEL_ITEM, PANEL_ITEM_SELECTABLE, PANEL_SEPARATOR, PANEL_MOTION } from "@glinui/ui"
```

## Usage

Icon buttons labelled by tooltips with shortcuts. Italic is pinned open so the label is visible at a glance.

```tsx
"use client"

import { Image, Link as LinkIcon, TextB, TextItalic, TextUnderline } from "@phosphor-icons/react"
import {
  Button,
  Kbd,
  Text,
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger
} from "@glinui/ui"

const CARD = "mx-auto w-full rounded-2xl border border-[var(--line-soft)] bg-[var(--surface-1)] p-5 [box-shadow:var(--elev-1)]"

export function TooltipToolbarHero() {
  const tools = [
    { icon: TextB, label: "Bold", keys: "Ctrl B" },
    { icon: TextItalic, label: "Italic", keys: "Ctrl I" },
    { icon: TextUnderline, label: "Underline", keys: "Ctrl U" },
    { icon: LinkIcon, label: "Insert link", keys: "Ctrl K" },
    { icon: Image, label: "Insert image", keys: "Ctrl Shift I" }
  ]
  return (
    <TooltipProvider delayDuration={200}>
      <div className={`${CARD} max-w-md pt-14`}>
        <div role="toolbar" aria-label="Text formatting" className="flex flex-wrap items-center gap-1 rounded-xl border border-[var(--line-soft)] p-1">
          {tools.map(({ icon: Icon, label, keys }, index) => (
            <Tooltip key={label} defaultOpen={index === 1}>
              <TooltipTrigger asChild>
                <Button size="icon" variant="ghost" aria-label={label}><Icon aria-hidden="true" /></Button>
              </TooltipTrigger>
              <TooltipContent side="top">{label} <Kbd size="sm">{keys}</Kbd></TooltipContent>
            </Tooltip>
          ))}
        </div>
        <p className="mt-4 text-sm text-[var(--color-muted)]">Hover or focus a button to see its name and shortcut.</p>
      </div>
    </TooltipProvider>
  )
}
```

### Sides

Tooltips on all four sides, plus an explanation on a disabled action.

```tsx
"use client"

import { DownloadSimple } from "@phosphor-icons/react"
import {
  Button,
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger
} from "@glinui/ui"

export function TooltipSidesExample() {
  return (
    <TooltipProvider delayDuration={100}>
      <div className="mx-auto flex flex-wrap items-center justify-center gap-3 py-8">
        {(["top", "right", "bottom", "left"] as const).map((side) => (
          <Tooltip key={side}>
            <TooltipTrigger asChild><Button variant="outline" size="sm">{side}</Button></TooltipTrigger>
            <TooltipContent side={side}>{`Opens on the ${side}`}</TooltipContent>
          </Tooltip>
        ))}
        <Tooltip>
          <TooltipTrigger asChild><Button size="sm" disabled aria-label="Export, unavailable"><DownloadSimple aria-hidden="true" />Export</Button></TooltipTrigger>
          <TooltipContent>Export is unavailable on the free plan</TooltipContent>
        </Tooltip>
      </div>
    </TooltipProvider>
  )
}
```

### Glass (opt-in)

variant="glass" is opt-in. It blurs and tints what sits behind the panel (with a readable opacity floor), so it needs a colourful or photographic backdrop: switch the stage backdrop to see it.

```tsx
import { Button, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@glinui/ui"

export function Demo() {
  return (
    <TooltipProvider delayDuration={0}>
      <Tooltip>
        <TooltipTrigger asChild><Button variant="outline">Hover me</Button></TooltipTrigger>
        <TooltipContent variant="glass">Frosted tooltip</TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}
```

## Props

### TooltipContentProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `container?` | `HTMLElement \| null` |  | Element to portal into. Defaults to document.body. |
| `side?` | `"top" \| "right" \| "bottom" \| "left"` |  | Preferred side for tooltip content. |
| `sideOffset?` | `number` | `6` | Gap in px between trigger and content. |
| `variant?` | `PanelVariantProp` |  | Surface look. Omit for the ambient design style: a compact high-contrast pill that inverts per theme scope (dark pill in light, light pil... |

### TooltipProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultOpen?` | `boolean` |  | Initial open state for uncontrolled usage. |
| `delayDuration?` | `number` |  | Delay in ms before showing tooltip content. |
| `onOpenChange?` | `(open: boolean) => void` |  | Callback when open state changes. |
| `open?` | `boolean` |  | Controlled open state. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Built on Radix Tooltip with `role="tooltip"`.
- Shows on hover and focus.
- TooltipProvider wraps the usage context.
- Built on Radix Tooltip; the content is linked via `aria-describedby` on the trigger automatically.
- Tooltip opens on focus as well as hover, ensuring keyboard users receive the same context hints.
- Do not place interactive elements (buttons, links) inside `TooltipContent`, use a Popover for that pattern.
- Keep tooltip text to a single short phrase. For longer explanations, prefer an inline description.

Keyboard:

| Key | Action |
| --- | --- |
| Escape | Dismiss the tooltip when focused. |

ARIA:

- `role="tooltip"`
- `aria-describedby` linking trigger to tooltip content

- Reduced motion: Show/hide transitions respect `prefers-reduced-motion`. Tooltip fade and scale transitions respect `prefers-reduced-motion`. When enabled, the content appears instantly without animation.

---

# Dropdown Menu

> Action menu anchored to a trigger with keyboard navigation.

- id: `dropdown-menu`
- type: primitive
- category: Overlays and menus
- tags: primitive
- docs: https://glinui.com/docs/components/radix/dropdown-menu
- markdown: https://glinui.com/md/dropdown-menu.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add dropdown-menu
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/dropdown-menu.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuLabel } from "@glinui/ui"
```

## Usage

An account menu opened by default: identity row with a plan badge, grouped items with icons and shortcuts, and a destructive sign out.

```tsx
"use client"

import { CreditCard, Cube, GearSix, Lifebuoy, PencilSimple, SignOut } from "@phosphor-icons/react"
import {
  Avatar,
  Badge,
  Button,
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuSeparator,
  DropdownMenuShortcut,
  DropdownMenuTrigger
} from "@glinui/ui"

export function DropdownAccountHero() {
  return (
    <div className="mx-auto min-h-96 w-full max-w-lg">
      <div className="flex items-center justify-between gap-3 rounded-2xl border border-[var(--line-soft)] bg-[var(--surface-1)] px-4 py-2.5 [box-shadow:var(--elev-1)]">
        <span className="flex items-center gap-2 text-sm font-semibold"><Cube aria-hidden="true" className="size-4" />Lumen</span>
        <DropdownMenu defaultOpen modal={false}>
          <DropdownMenuTrigger asChild>
            <Button variant="ghost" className="h-auto gap-2 px-2 py-1" aria-label="Account menu">
              <Avatar size="sm" fallback="AK" alt="" status="online" />
              <span className="hidden text-sm font-medium sm:inline">Ava Kim</span>
            </Button>
          </DropdownMenuTrigger>
          <DropdownMenuContent align="end" className="w-64">
            <DropdownMenuLabel className="flex items-center justify-between gap-2">
              <span className="grid"><span className="text-sm font-medium">Ava Kim</span><span className="text-xs font-normal text-[var(--color-muted)]">ava@lumen.test</span></span>
              <Badge size="sm" tone="accent">Pro</Badge>
            </DropdownMenuLabel>
            <DropdownMenuSeparator />
              <DropdownMenuItem><PencilSimple aria-hidden="true" className="size-4" />Profile<DropdownMenuShortcut>Ctrl P</DropdownMenuShortcut></DropdownMenuItem>
              <DropdownMenuItem><CreditCard aria-hidden="true" className="size-4" />Billing<DropdownMenuShortcut>Ctrl B</DropdownMenuShortcut></DropdownMenuItem>
              <DropdownMenuItem><GearSix aria-hidden="true" className="size-4" />Settings<DropdownMenuShortcut>Ctrl ,</DropdownMenuShortcut></DropdownMenuItem>
            <DropdownMenuSeparator />
            <DropdownMenuItem><Lifebuoy aria-hidden="true" className="size-4" />Support</DropdownMenuItem>
            <DropdownMenuSeparator />
            <DropdownMenuItem className="text-[var(--tone-danger-text)]"><SignOut aria-hidden="true" className="size-4" />Sign out<DropdownMenuShortcut>Shift Q</DropdownMenuShortcut></DropdownMenuItem>
          </DropdownMenuContent>
        </DropdownMenu>
      </div>
    </div>
  )
}
```

### Row actions

A trigger menu at the end of a file row.

```tsx
"use client"

import { BookmarkSimple, Copy, DownloadSimple, FileText, Trash } from "@phosphor-icons/react"
import {
  Button,
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
  IconFrame
} from "@glinui/ui"

const CARD = "mx-auto w-full rounded-2xl border border-[var(--line-soft)] bg-[var(--surface-1)] p-5 [box-shadow:var(--elev-1)]"

export function DropdownRowActionsExample() {
  return (
    <div className={`${CARD} max-w-md`}>
      <div className="flex items-center gap-3">
        <IconFrame size="sm"><FileText aria-hidden="true" /></IconFrame>
        <span className="grid min-w-0 flex-1 text-sm"><span className="font-medium">Vendor agreement.pdf</span><span className="text-xs text-[var(--color-muted)]">2.4 MB, edited yesterday</span></span>
        <DropdownMenu>
          <DropdownMenuTrigger asChild><Button size="icon" variant="ghost" aria-label="File actions">...</Button></DropdownMenuTrigger>
          <DropdownMenuContent align="end">
            <DropdownMenuItem><DownloadSimple aria-hidden="true" className="size-4" />Download</DropdownMenuItem>
            <DropdownMenuItem><Copy aria-hidden="true" className="size-4" />Duplicate</DropdownMenuItem>
            <DropdownMenuItem><BookmarkSimple aria-hidden="true" className="size-4" />Add to favorites</DropdownMenuItem>
            <DropdownMenuSeparator />
            <DropdownMenuItem className="text-[var(--tone-danger-text)]"><Trash aria-hidden="true" className="size-4" />Delete</DropdownMenuItem>
          </DropdownMenuContent>
        </DropdownMenu>
      </div>
    </div>
  )
}
```

### Glass (opt-in)

Glass is opt-in and needs a colourful or photographic backdrop to read as frosted. Pick one in the stage header.

```tsx
import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem } from "@glinui/ui"

export function Demo() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger>Glass menu</DropdownMenuTrigger>
      <DropdownMenuContent variant="glass">
        <DropdownMenuItem>Profile</DropdownMenuItem>
        <DropdownMenuItem>Billing</DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}
```

## Props

### DropdownMenuCheckboxItemProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from dropdownMenuItemVariants. |
| `variant?` | `"default" \| "glass" \| "frosted" \| "outline" \| "ghost"` | `"default"` | Variant option from dropdownMenuItemVariants. |

### DropdownMenuContentProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `container?` | `HTMLElement \| null` |  | Element to portal into. Defaults to document.body. |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from dropdownMenuContentVariants. |
| `variant?` | `PanelVariantProp` |  | Surface look. Omit for the ambient design style (glinr by default). `glass` is opt-in and needs a rich backdrop. |

### DropdownMenuItemProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `inset?` | `boolean` |  |  |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from dropdownMenuItemVariants. |
| `variant?` | `"default" \| "glass" \| "frosted" \| "outline" \| "ghost"` | `"default"` | Variant option from dropdownMenuItemVariants. |

### DropdownMenuLabelProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `inset?` | `boolean` |  |  |

### DropdownMenuRadioItemProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from dropdownMenuItemVariants. |
| `variant?` | `"default" \| "glass" \| "frosted" \| "outline" \| "ghost"` | `"default"` | Variant option from dropdownMenuItemVariants. |

### DropdownMenuSubContentProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from dropdownMenuContentVariants. |
| `variant?` | `PanelVariantProp` |  |  |

### DropdownMenuSubTriggerProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `inset?` | `boolean` |  |  |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from dropdownMenuItemVariants. |
| `variant?` | `"default" \| "glass" \| "frosted" \| "outline" \| "ghost"` | `"default"` | Variant option from dropdownMenuItemVariants. |

### DropdownMenuTriggerProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from dropdownMenuTriggerVariants. |
| `variant?` | `"default" \| "glass" \| "frosted" \| "outline" \| "ghost"` | `"default"` | Variant option from dropdownMenuTriggerVariants. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`, `glass`, `frosted`, `outline`, `ghost`.

## Accessibility

- Built on Radix DropdownMenu with full WAI-ARIA.
- Focus is trapped within the menu when open.
- Supports keyboard navigation, escape, and focus restore.

Keyboard:

| Key | Action |
| --- | --- |
| Enter / Space | Open the menu or select an item. |
| Arrow Up / Down | Navigate between menu items. |
| Arrow Right | Open a submenu. |
| Arrow Left | Close a submenu. |
| Escape | Close the menu. |

ARIA:

- `role="menu"`
- `role="menuitem"`
- `aria-expanded`
- `aria-haspopup`

- Reduced motion: Open/close transitions respect `prefers-reduced-motion`. Menu open/close should remain readable without animation.

---

# Context Menu

> Right-click menu with items, checkbox and radio items, submenus and shortcuts.

- id: `context-menu`
- type: primitive
- category: Overlays and menus
- tags: primitive
- docs: https://glinui.com/docs/components/radix/context-menu
- markdown: https://glinui.com/md/context-menu.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add context-menu
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/context-menu.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { ContextMenu, ContextMenuTrigger, ContextMenuGroup, ContextMenuPortal, ContextMenuSub, ContextMenuRadioGroup, ContextMenuContent, ContextMenuItem } from "@glinui/ui"
```

## Usage

Right click the card (or press and hold on touch) to open a menu with a submenu, a pinned toggle and a destructive item.

```tsx
"use client"

import { FileText, FolderSimple, Image } from "@phosphor-icons/react"
import {
  Badge,
  ContextMenu,
  ContextMenuCheckboxItem,
  ContextMenuContent,
  ContextMenuItem,
  ContextMenuLabel,
  ContextMenuSeparator,
  ContextMenuShortcut,
  ContextMenuSub,
  ContextMenuSubContent,
  ContextMenuSubTrigger,
  ContextMenuTrigger,
  Heading
} from "@glinui/ui"

const FILES = [
  { name: "brand-guidelines.pdf", size: "4.2 MB", icon: FileText },
  { name: "hero-banner.png", size: "1.1 MB", icon: Image },
  { name: "Roadmap", size: "12 items", icon: FolderSimple }
]

export function ContextFilesHero() {
  return (
    <div className="mx-auto w-full max-w-md">
      <ContextMenu>
        <ContextMenuTrigger className="block rounded-2xl border border-dashed border-[var(--color-border)] bg-[var(--surface-1)] p-4 [box-shadow:var(--elev-1)]">
          <div className="flex items-center justify-between gap-3 pb-3">
            <Heading level={3} size="sm">Design assets</Heading>
            <Badge size="sm">Right click anywhere</Badge>
          </div>
          <ul className="grid divide-y divide-[var(--line-soft)]">
            {FILES.map(({ name, size, icon: Icon }) => (
              <li key={name} className="flex items-center gap-3 py-2.5 text-sm">
                <Icon aria-hidden="true" className="size-5 text-[var(--color-muted)]" />
                <span className="flex-1">{name}</span>
                <span className="text-xs text-[var(--color-muted)]">{size}</span>
              </li>
            ))}
          </ul>
          <p className="pt-3 text-xs text-[var(--color-muted)]">On touch screens, press and hold. On a keyboard, use Shift F10.</p>
        </ContextMenuTrigger>
        <ContextMenuContent className="w-60">
          <ContextMenuLabel>brand-guidelines.pdf</ContextMenuLabel>
          <ContextMenuItem>Open <ContextMenuShortcut>Enter</ContextMenuShortcut></ContextMenuItem>
          <ContextMenuItem>Rename <ContextMenuShortcut>F2</ContextMenuShortcut></ContextMenuItem>
          <ContextMenuSub>
            <ContextMenuSubTrigger>Move to</ContextMenuSubTrigger>
            <ContextMenuSubContent>
              <ContextMenuItem>Roadmap</ContextMenuItem>
              <ContextMenuItem>Archive</ContextMenuItem>
            </ContextMenuSubContent>
          </ContextMenuSub>
          <ContextMenuSeparator />
          <ContextMenuCheckboxItem checked>Pin to top</ContextMenuCheckboxItem>
          <ContextMenuSeparator />
          <ContextMenuItem className="text-[var(--tone-danger-text)]">Delete <ContextMenuShortcut>Del</ContextMenuShortcut></ContextMenuItem>
        </ContextMenuContent>
      </ContextMenu>
    </div>
  )
}
```

### Canvas

A menu for an empty canvas, with checkable view options.

```tsx
"use client"

import { Globe, Plus } from "@phosphor-icons/react"
import {
  ContextMenu,
  ContextMenuCheckboxItem,
  ContextMenuContent,
  ContextMenuItem,
  ContextMenuSeparator,
  ContextMenuShortcut,
  ContextMenuTrigger
} from "@glinui/ui"

export function ContextCanvasExample() {
  return (
    <div className="mx-auto w-full max-w-md">
      <ContextMenu>
        <ContextMenuTrigger className="flex h-40 items-center justify-center rounded-2xl border border-dashed border-[var(--color-border)] bg-[var(--surface-1)] text-sm text-[var(--color-muted)]">
          Right click the canvas
        </ContextMenuTrigger>
        <ContextMenuContent className="w-56">
          <ContextMenuItem><Plus aria-hidden="true" className="size-4" />New frame <ContextMenuShortcut>F</ContextMenuShortcut></ContextMenuItem>
          <ContextMenuItem><Globe aria-hidden="true" className="size-4" />Paste here <ContextMenuShortcut>Ctrl V</ContextMenuShortcut></ContextMenuItem>
          <ContextMenuSeparator />
          <ContextMenuCheckboxItem checked>Show grid</ContextMenuCheckboxItem>
          <ContextMenuCheckboxItem>Snap to objects</ContextMenuCheckboxItem>
        </ContextMenuContent>
      </ContextMenu>
    </div>
  )
}
```

### Glass (opt-in)

Glass is opt-in and needs a colourful or photographic backdrop. Pick one in the stage header.

```tsx
import { ContextMenu, ContextMenuCheckboxItem, ContextMenuContent, ContextMenuItem, ContextMenuLabel, ContextMenuSeparator, ContextMenuShortcut, ContextMenuTrigger } from "@glinui/ui"

export function Demo() {
  return (
    <ContextMenu variant="glass">
      <ContextMenuTrigger className="flex h-32 w-72 items-center justify-center rounded-xl border border-dashed border-[var(--color-border)] text-sm text-[var(--color-muted)]">
        Right click here
      </ContextMenuTrigger>
      <ContextMenuContent className="w-56">
        <ContextMenuLabel>Actions</ContextMenuLabel>
        <ContextMenuItem>Back <ContextMenuShortcut>Cmd [</ContextMenuShortcut></ContextMenuItem>
        <ContextMenuItem>Reload <ContextMenuShortcut>Cmd R</ContextMenuShortcut></ContextMenuItem>
        <ContextMenuSeparator />
        <ContextMenuCheckboxItem checked>Show bookmarks</ContextMenuCheckboxItem>
      </ContextMenuContent>
    </ContextMenu>
  )
}
```

## Props

### ContextMenuContentProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant?` | `ContextMenuVariant` |  | Surface look. Omit for the ambient design style (glinr by default). `glass` is opt-in and needs a rich backdrop. |

### ContextMenuProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant?` | `ContextMenuVariant` |  | Surface treatment shared by every floating panel in this menu. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Opens on right click, long press on touch, or the keyboard context menu key.
- Focus moves into the menu and returns to the trigger on close.
- Check and radio items expose their checked state.

Keyboard:

| Key | Action |
| --- | --- |
| Shift + F10 / Menu key | Open the menu from the focused trigger. |
| ArrowUp / ArrowDown | Move between items. |
| ArrowRight / ArrowLeft | Open or close a submenu. |
| Enter / Space | Select the focused item. |
| Escape | Close the menu. |

ARIA:

- `role="menu"` and `menuitem`
- `aria-checked` on checkbox and radio items
- `aria-disabled` on disabled items

- Reduced motion: Panels fade and scale from 95% on open using transform and opacity only. With prefers-reduced-motion the animation is removed.

---

# Command

> Command palette for keyboard-driven actions and search.

- id: `command`
- type: primitive
- category: Overlays and menus
- tags: primitive
- docs: https://glinui.com/docs/components/radix/command
- markdown: https://glinui.com/md/command.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add command
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/command.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Command, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandSeparator, CommandItem, CommandShortcut } from "@glinui/ui"
```

## Usage

A palette with recent items, suggestions and settings, each with an icon and shortcut. Type to filter.

```tsx
"use client"

import { CreditCard, FileText, FolderSimple, GearSix, MagnifyingGlass, Plus, UserPlus } from "@phosphor-icons/react"
import {
  Command,
  CommandEmpty,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
  CommandSeparator,
  CommandShortcut,
  Kbd
} from "@glinui/ui"

export function CommandPaletteHero() {
  return (
    <div className="mx-auto w-full max-w-lg">
      <Command className="rounded-2xl border border-[var(--line-soft)] [box-shadow:var(--elev-2)]">
        <CommandInput placeholder="Search pages, people and commands" />
        <CommandList className="max-h-72">
          <CommandEmpty>No results for that search.</CommandEmpty>
          <CommandGroup heading="Recent">
            <CommandItem><FileText aria-hidden="true" className="size-4" />Q4 roadmap</CommandItem>
            <CommandItem><FolderSimple aria-hidden="true" className="size-4" />Brand assets</CommandItem>
          </CommandGroup>
          <CommandSeparator />
          <CommandGroup heading="Suggestions">
            <CommandItem><Plus aria-hidden="true" className="size-4" />New document<CommandShortcut>Ctrl N</CommandShortcut></CommandItem>
            <CommandItem><UserPlus aria-hidden="true" className="size-4" />Invite teammate<CommandShortcut>Ctrl I</CommandShortcut></CommandItem>
            <CommandItem><MagnifyingGlass aria-hidden="true" className="size-4" />Search workspace<CommandShortcut>Ctrl F</CommandShortcut></CommandItem>
          </CommandGroup>
          <CommandSeparator />
          <CommandGroup heading="Settings">
            <CommandItem><GearSix aria-hidden="true" className="size-4" />Preferences<CommandShortcut>Ctrl ,</CommandShortcut></CommandItem>
            <CommandItem><CreditCard aria-hidden="true" className="size-4" />Billing</CommandItem>
          </CommandGroup>
        </CommandList>
        <div className="flex items-center justify-between gap-3 border-t border-[var(--line-soft)] px-3 py-2 text-xs text-[var(--color-muted)]">
          <span className="flex items-center gap-1"><Kbd size="sm">Up</Kbd><Kbd size="sm">Down</Kbd> to move</span>
          <span className="flex items-center gap-1"><Kbd size="sm">Enter</Kbd> to open</span>
        </div>
      </Command>
    </div>
  )
}
```

### Assign to

The same component as a people picker, pre-filtered by the typed letter.

```tsx
"use client"

import {
  Avatar,
  Command,
  CommandEmpty,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
  CommandShortcut
} from "@glinui/ui"

export function CommandUsersExample() {
  const people = [
    { name: "Ava Kim", role: "Owner", initials: "AK" },
    { name: "Jon Reyes", role: "Admin", initials: "JR" },
    { name: "Sara Patel", role: "Editor", initials: "SP" },
    { name: "Mia Chen", role: "Viewer", initials: "MC" }
  ]
  return (
    <div className="mx-auto w-full max-w-sm">
      <Command className="rounded-2xl border border-[var(--line-soft)]">
        <CommandInput placeholder="Assign to..." defaultValue="a" />
        <CommandList>
          <CommandEmpty>Nobody matches that name.</CommandEmpty>
          <CommandGroup heading="People">
            {people.map((person) => (
              <CommandItem key={person.name} value={person.name}>
                <Avatar size="xs" fallback={person.initials} alt="" />
                {person.name}
                <CommandShortcut>{person.role}</CommandShortcut>
              </CommandItem>
            ))}
          </CommandGroup>
        </CommandList>
      </Command>
    </div>
  )
}
```

### Glass (opt-in)

variant="glass" is opt-in. It blurs and tints what sits behind the panel (with a readable opacity floor), so it needs a colourful or photographic backdrop: switch the stage backdrop to see it.

```tsx
import { Command, CommandGroup, CommandInput, CommandItem, CommandList } from "@glinui/ui"

export function Demo() {
  return (
    <Command variant="glass" className="max-w-md">
      <CommandInput placeholder="Search..." />
      <CommandList>
        <CommandGroup heading="Actions">
          <CommandItem>Open settings</CommandItem>
          <CommandItem>Invite teammate</CommandItem>
        </CommandGroup>
      </CommandList>
    </Command>
  )
}
```

## Props

### CommandProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from commandVariants. |
| `variant?` | `PanelVariantProp` |  | Surface look. Omit for the ambient design style (glinr by default). `glass` is opt-in and needs a rich backdrop to read as frosted. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Built on cmdk with keyboard-first navigation.
- Input auto-focuses for immediate search.
- Keyboard navigation and roving focus are provided by `cmdk`.
- Do not rely on placeholder text as a label. Provide an explicit `aria-label` or visible label for `CommandInput`.
- Keep command groups concise to reduce cognitive load.
- `CommandEmpty` provides a visible fallback for screen readers.

Keyboard:

| Key | Action |
| --- | --- |
| Arrow Up / Down | Navigate between items. |
| Enter | Select the highlighted item. |
| Escape | Close the command palette. |

ARIA:

- `role="listbox"` on list
- `role="option"` on items
- `aria-selected`

- Reduced motion: List transitions respect `prefers-reduced-motion`. Command interactions are state-based with no transform-heavy animations. Motion respects `prefers-reduced-motion` automatically.

---

# Alert

> Contextual feedback message with default, glass, outline, and ghost variants.

- id: `alert`
- type: primitive
- category: Feedback and status
- tags: primitive
- docs: https://glinui.com/docs/components/radix/alert
- markdown: https://glinui.com/md/alert.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add alert
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/alert.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Alert, AlertTitle, AlertDescription, SURFACE_VARIANTS, SURFACE_TONES, SURFACE_ELEVATIONS, SURFACE_VARIANT_ALIASES, STYLE_DEFAULT_VARIANT } from "@glinui/ui"
```

## Usage

In-context banners for each tone, with actions where the next step is obvious.

```tsx
import { Alert, AlertDescription, AlertTitle, Button } from "@glinui/ui"

export function Demo() {
  return (
    <div className="flex w-full max-w-xl flex-col gap-3">
      <Alert tone="info">
        <AlertTitle>Version 2.4 is available</AlertTitle>
        <AlertDescription>Adds scheduled exports and fixes two sync bugs.</AlertDescription>
        <div className="mt-3 flex flex-wrap gap-2">
          <Button size="sm">Update now</Button>
          <Button size="sm" variant="ghost">Release notes</Button>
        </div>
      </Alert>
      <Alert tone="success">
        <AlertTitle>Invoice INV-2041 paid</AlertTitle>
        <AlertDescription>Northwind Studio paid $1,240.00 by card.</AlertDescription>
      </Alert>
      <Alert tone="warning">
        <AlertTitle>92 percent of build minutes used</AlertTitle>
        <AlertDescription>Builds pause at 100 percent. The quota resets on Nov 1.</AlertDescription>
        <div className="mt-3 flex flex-wrap gap-2">
          <Button size="sm" variant="outline">Upgrade plan</Button>
        </div>
      </Alert>
      <Alert tone="danger">
        <AlertTitle>Deploy to production failed</AlertTitle>
        <AlertDescription>Migration 0042 timed out after 60 seconds. The previous release is still live.</AlertDescription>
        <div className="mt-3 flex flex-wrap gap-2">
          <Button size="sm" variant="outline">View logs</Button>
          <Button size="sm" variant="ghost">Retry</Button>
        </div>
      </Alert>
    </div>
  )
}
```

### Variants

glinr is the default. plain is flat shadcn. glass is opt-in and needs a backdrop.

```tsx
import { Alert } from "@glinui/ui"

<Alert variant="glinr" tone="accent" icon />
<Alert variant="plain" tone="accent" icon />
<Alert variant="solid" tone="accent" icon />
<Alert variant="soft" tone="accent" icon />
<Alert variant="glass" tone="accent" icon />
```

### Dismissible and quiet looks

A banner you can dismiss, plus the note and flag looks for low-key asides.

```tsx
import { useState } from "react"
import { ArrowClockwise } from "@phosphor-icons/react"
import { Alert, AlertDescription, AlertTitle, Button } from "@glinui/ui"

export function Demo() {
  const [open, setOpen] = useState(true)
  return (
    <div className="flex w-full max-w-xl flex-col gap-3">
      {open ? (
        <Alert tone="accent" icon>
          <AlertTitle>Invite your team</AlertTitle>
          <AlertDescription>Projects with two or more members ship twice as often.</AlertDescription>
          <div className="mt-3 flex flex-wrap gap-2">
            <Button size="sm">Invite teammates</Button>
            <Button size="sm" variant="ghost" onClick={() => setOpen(false)}>Dismiss</Button>
          </div>
        </Alert>
      ) : (
        <Button variant="outline" size="sm" className="w-fit" onClick={() => setOpen(true)}>
          <ArrowClockwise aria-hidden className="size-4" />
          Show banner again
        </Button>
      )}
      <Alert variant="note">
        <AlertTitle>Note</AlertTitle>
        <AlertDescription>Quiet aside for tips that do not need a tone.</AlertDescription>
      </Alert>
      <Alert variant="flag">
        <AlertTitle>Flag</AlertTitle>
        <AlertDescription>Brand-colored callout for launches and announcements.</AlertDescription>
      </Alert>
    </div>
  )
}
```

## Props

### AlertProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon?` | `boolean \| React.ReactNode` |  | `true` renders the tone icon, a node renders a custom icon, `false` hides it. Defaults to the tone icon when a non-neutral `tone` is set. |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from alertSizeVariants. |
| `tone?` | `SurfaceTone` |  | Tone for the accent bar, tint and icon. |
| `variant?` | `AlertVariant \| null` |  | Surface look. Omitted follows the ambient style (glinr by default, plain for minimal). Vocabulary: glinr, solid, plain, soft, outline, gh... |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Uses `role="alert"` by default.
- Keep alert text concise and actionable.
- Prefer one alert per context region.
- Root component uses `role="alert"` by default.
- Prefer one alert per context region to avoid screen reader noise.

ARIA:

- `role="alert"` native
- `aria-live="assertive"`

- Reduced motion: Alert is static and does not rely on animation.

---

# Toast

> Glassmorphic toast notifications powered by Sonner with success, error, warning, info, loading, promise, and action support.

- id: `toast`
- type: primitive
- category: Feedback and status
- tags: primitive
- docs: https://glinui.com/docs/components/radix/toast
- markdown: https://glinui.com/md/toast.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add toast
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/toast.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { ToastProvider, ToastViewport, Toast, ToastTitle, ToastDescription, ToastClose, Toaster, PANEL_ITEM } from "@glinui/ui"
```

## Usage

A Save button triggers a success toast with an Undo action that reverts the change.

```tsx
"use client"

import * as React from "react"
import {
  Avatar,
  Button,
  Heading,
  Text,
  Toaster,
  toast
} from "@glinui/ui"

export function ToastSaveHero() {
  const [saves, setSaves] = React.useState(0)
  return (
    <div className="mx-auto grid w-full max-w-md gap-4 rounded-2xl border border-[var(--line-soft)] bg-[var(--surface-1)] p-5 [box-shadow:var(--elev-1)]">
      <Toaster position="bottom-right" />
      <div>
        <Heading level={3} size="sm">Profile</Heading>
        <Text size="sm" className="mt-1 text-[var(--color-muted)]">Changes to your display name and photo apply across the workspace.</Text>
      </div>
      <div className="flex items-center gap-3">
        <Avatar size="md" fallback="AK" alt="" />
        <div className="grid text-sm">
          <span className="font-medium">Ava Kim</span>
          <span className="text-[var(--color-muted)]">{saves} saves this session</span>
        </div>
      </div>
      <div className="flex justify-end">
        <Button
          onClick={() => {
            setSaves((n) => n + 1)
            toast.success("Profile saved", {
              description: "Your changes are live for everyone in Lumen.",
              action: {
                label: "Undo",
                onClick: () => {
                  setSaves((n) => Math.max(0, n - 1))
                  toast("Changes reverted")
                }
              }
            })
          }}
        >
          Save changes
        </Button>
      </div>
    </div>
  )
}
```

### Stacked variants

Fire several toasts in a row: they stack, collapse and can be dismissed with the close button.

```tsx
"use client"

import { Trash, Warning, X } from "@phosphor-icons/react"
import {
  Button,
  Heading,
  Text,
  Toaster,
  toast
} from "@glinui/ui"

export function ToastStackHero() {
  return (
    <div className="mx-auto grid w-full max-w-md gap-4 rounded-2xl border border-[var(--line-soft)] bg-[var(--surface-1)] p-5 [box-shadow:var(--elev-1)]">
      <Toaster position="bottom-right" closeButton visibleToasts={4} />
      <div>
        <Heading level={3} size="sm">Notification variants</Heading>
        <Text size="sm" className="mt-1 text-[var(--color-muted)]">Fire a few in a row to see them stack and collapse.</Text>
      </div>
      <div className="flex flex-wrap gap-2">
        <Button size="sm" onClick={() => toast.success("Deploy finished", { description: "lumen-web is live on production." })}>Success</Button>
        <Button size="sm" variant="outline" onClick={() => toast.warning("Storage almost full", { description: "You have used 92 percent of your plan." })}>
          <Warning aria-hidden="true" />
          Warning
        </Button>
        <Button size="sm" variant="outline" onClick={() => toast.error("Payment failed", { description: "Your card ending 4242 was declined." })}>
          <X aria-hidden="true" />
          Error
        </Button>
        <Button size="sm" variant="outline" onClick={() => toast("File deleted", { description: "launch-banner.png moved to trash.", action: { label: "Undo", onClick: () => toast.success("Restored") } })}>
          <Trash aria-hidden="true" />
          With undo
        </Button>
      </div>
    </div>
  )
}
```

### Action Button

```tsx
import { Toaster, toast, Button } from "@glinui/ui"

export function Demo() {
  return (
    <>
      <Toaster position="bottom-right" />
      <Button onClick={() => toast("File deleted", {
        description: "The file has been moved to trash.",
        action: { label: "Undo", onClick: () => toast.success("Restored") }
      })}>
        With action
      </Button>
    </>
  )
}
```

## Props

### ToastProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from toastVariants. |
| `tone?` | `"none" \| "success" \| "warning" \| "danger" \| "info"` | `"none"` | Variant option from toastVariants. |
| `variant?` | `PanelVariantProp \| ToastStatus` |  | Surface look, or a status (`success`, `warning`, `destructive`, `info`) which keeps the ambient look and adds a status bar. Omit for the ... |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Built on Sonner with ARIA live region announcements.
- Auto-pause on hover for reading time.
- Swipe-to-dismiss with configurable directions.
- Keyboard accessible with hotkey support.
- Auto-pause on hover gives users time to read.
- Keep toast messages short (under 140 characters) for screen readers.

Keyboard:

| Key | Action |
| --- | --- |
| Escape | Dismiss the focused toast. |
| Alt+T | Focus the toast region (configurable). |

ARIA:

- `role="status"` on toast region
- `aria-live` for live announcements
- `aria-label` on close and action buttons

- Reduced motion: Slide and opacity transitions respect `prefers-reduced-motion`. Slide and opacity transitions respect `prefers-reduced-motion`. When enabled, toasts fade in without translate animation.

---

# Spinner

> Accessible loading indicator with a reduced-motion pulsing ring fallback.

- id: `spinner`
- type: primitive
- category: Feedback and status
- tags: primitive
- docs: https://glinui.com/docs/components/radix/spinner
- markdown: https://glinui.com/md/spinner.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add spinner
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/spinner.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Spinner, CONTROL_LEGACY_VARIANTS, CONTROL_SIZE_CLASSES, GlinProvider, GLIN_MOTIONS, GLIN_ENGINES, GLIN_SURFACES, GLIN_STYLES } from "@glinui/ui"
```

## Usage

Inside a button while saving, and as a full-section loader.

```tsx
import { useEffect, useState } from "react"
import { Button, Card, Spinner } from "@glinui/ui"

export function Demo() {
  const [saving, setSaving] = useState(false)
  useEffect(() => {
    if (!saving) return
    const id = window.setTimeout(() => setSaving(false), 2400)
    return () => window.clearTimeout(id)
  }, [saving])
  return (
    <div className="flex w-full max-w-md flex-col gap-6">
      <div className="flex flex-wrap items-center gap-3">
        <Button disabled={saving} onClick={() => setSaving(true)}>
          {saving ? <Spinner size="sm" variant="current" label="Saving" /> : null}
          {saving ? "Saving changes" : "Save changes"}
        </Button>
        <Button variant="outline" disabled>
          <Spinner size="sm" variant="current" label="Syncing" />
          Syncing
        </Button>
        <Button variant="ghost" size="sm" disabled>
          <Spinner size="sm" variant="current" label="Loading" />
          Loading
        </Button>
      </div>
      <Card className="flex flex-col items-center gap-3 py-10 text-center" aria-busy="true">
        <Spinner size="lg" label="Loading dashboard" />
        <div>
          <p className="text-sm font-medium">Loading your dashboard</p>
          <p className="text-sm text-[var(--color-muted)]">Fetching the latest numbers</p>
        </div>
      </Card>
    </div>
  )
}
```

### Variants

```tsx
import { Spinner } from "@glinui/ui"

export function Demo() {
  return (
    <div className="flex flex-wrap items-center gap-4">
      <Spinner variant="glinr" label="glinr" />
      <Spinner variant="solid" label="solid" />
      <Spinner variant="plain" label="plain" />
      <Spinner variant="soft" label="soft" />
      <Spinner variant="outline" label="outline" />
      <Spinner variant="ghost" label="ghost" />
      <Spinner variant="muted" label="muted" />
    </div>
  )
}
```

### Sizes

Four sizes and a muted look for quiet surfaces.

```tsx
import { Spinner } from "@glinui/ui"

export function Demo() {
  return (
    <div className="flex flex-wrap items-end gap-8">
      {(["sm", "md", "lg", "xl"] as const).map((size) => (
        <div key={size} className="flex flex-col items-center gap-2">
          <Spinner size={size} label={`Loading ${size}`} />
          <span className="font-mono text-xs text-[var(--color-muted)]">{size}</span>
        </div>
      ))}
      <div className="flex flex-col items-center gap-2">
        <Spinner size="lg" variant="muted" label="Loading muted" />
        <span className="font-mono text-xs text-[var(--color-muted)]">muted</span>
      </div>
    </div>
  )
}
```

## Props

### SpinnerProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label?` | `string` | `"Loading"` | Accessible label announced to assistive tech. |
| `size?` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` | Variant option from spinnerVariants. |
| `variant?` | `ControlVariantProp \| "muted" \| "current"` |  | Color treatment. Omit to follow the ambient design style (glinr = accent, minimal = foreground). Also: solid, soft, outline, ghost, glass... |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `muted`, `current`.

## Accessibility

- Renders `role="status"` with an `aria-label`, announcing politely to assistive tech.
- Visual shapes are `aria-hidden`; do not rely on them for meaning.

ARIA:

- `role="status"`
- `aria-label` (defaults to `Loading`)

- Reduced motion: Rotation is replaced by a ring of dots that pulses in opacity.

---

# Skeleton

> Loading placeholder surface with reduced-motion fallback.

- id: `skeleton`
- type: primitive
- category: Feedback and status
- tags: primitive
- docs: https://glinui.com/docs/components/radix/skeleton
- markdown: https://glinui.com/md/skeleton.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add skeleton
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/skeleton.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Skeleton, CONTROL_LEGACY_VARIANTS, CONTROL_SIZE_CLASSES, GlinProvider, GLIN_MOTIONS, GLIN_ENGINES, GLIN_SURFACES, GLIN_STYLES } from "@glinui/ui"
```

## Usage

A loading post placeholder next to the content it mirrors, so the layout does not jump.

```tsx
import { Avatar, Badge, Card, Skeleton } from "@glinui/ui"

export function Demo() {
  return (
    <div className="grid w-full max-w-3xl gap-4 md:grid-cols-2">
      <Card className="flex flex-col gap-4" aria-busy="true" aria-label="Loading post">
        <div className="flex items-center gap-3">
          <Skeleton className="size-10 rounded-full" />
          <div className="flex flex-1 flex-col gap-2">
            <Skeleton className="h-3.5 w-1/3" />
            <Skeleton className="h-3 w-1/4" />
          </div>
        </div>
        <div className="flex flex-col gap-2">
          <Skeleton className="h-3.5 w-full" />
          <Skeleton className="h-3.5 w-11/12" />
          <Skeleton className="h-3.5 w-2/3" />
        </div>
        <Skeleton className="h-32 w-full rounded-lg" />
        <div className="flex gap-2">
          <Skeleton className="h-8 w-20 rounded-full" />
          <Skeleton className="h-8 w-20 rounded-full" />
        </div>
      </Card>
      <Card className="flex flex-col gap-4">
        <div className="flex items-center gap-3">
          <Avatar fallback="MK" tone="accent" />
          <div className="flex flex-col">
            <span className="text-sm font-medium">Maya Kovacs</span>
            <span className="text-xs text-[var(--color-muted)]">Product designer, 2h ago</span>
          </div>
        </div>
        <p className="text-sm">
          Shipped the new billing page today. The empty states took longer than the happy path, but they
          feel much better now.
        </p>
        <div className="flex h-32 w-full items-center justify-center rounded-lg bg-[var(--surface-3)] text-sm text-[var(--color-muted)]">
          billing-page.png
        </div>
        <div className="flex gap-2">
          <Badge variant="soft">24 likes</Badge>
          <Badge variant="soft">6 comments</Badge>
        </div>
      </Card>
    </div>
  )
}
```

### Variants

```tsx
import { Skeleton } from "@glinui/ui"

export function Demo() {
  return (
    <div className="grid gap-3 sm:grid-cols-2">
      <Skeleton variant="glinr" className="h-6 w-full" />
      <Skeleton variant="solid" className="h-6 w-full" />
      <Skeleton variant="plain" className="h-6 w-full" />
      <Skeleton variant="soft" className="h-6 w-full" />
      <Skeleton variant="outline" className="h-6 w-full" />
      <Skeleton variant="ghost" className="h-6 w-full" />
    </div>
  )
}
```

### Loading to loaded

Swap the skeleton for real content and flip aria-busy.

```tsx
import { useState } from "react"
import { Avatar, Button, Card, Skeleton } from "@glinui/ui"

export function Demo() {
  const [loading, setLoading] = useState(true)
  return (
    <div className="flex w-full max-w-sm flex-col gap-4">
      <Button variant="outline" size="sm" className="w-fit" onClick={() => setLoading((value) => !value)}>
        {loading ? "Show loaded state" : "Show loading state"}
      </Button>
      <Card className="flex items-center gap-4" aria-busy={loading}>
        {loading ? (
          <>
            <Skeleton className="size-12 rounded-full" />
            <div className="flex flex-1 flex-col gap-2">
              <Skeleton className="h-4 w-2/3" />
              <Skeleton className="h-3 w-1/2" />
            </div>
          </>
        ) : (
          <>
            <Avatar fallback="JO" size="lg" tone="success" />
            <div className="flex flex-col">
              <span className="font-medium">Jonas Okafor</span>
              <span className="text-sm text-[var(--color-muted)]">Engineering manager</span>
            </div>
          </>
        )}
      </Card>
    </div>
  )
}
```

## Props

### SkeletonProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `decorative?` | `boolean` | `true` |  |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from skeletonVariants. |
| `variant?` | `ControlVariantProp` |  | Placeholder look. Omit to follow the ambient design style (glinr = inset well). Same vocabulary as Input. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Sets `aria-hidden` when decorative.
- Uses `motion-safe:animate-pulse` with `motion-reduce:animate-none`.
- Decorative placeholders default to `aria-hidden` so screen readers skip them.
- Set `decorative={false}` and add `role="status"` with `aria-live="polite"` for semantic loading regions.
- Avoid stacking more than 5-6 skeletons without a loading boundary to limit screen reader noise.

ARIA:

- `aria-hidden="true"` when decorative
- `aria-busy="true"` on parent container

- Reduced motion: Pulse animation disabled with `prefers-reduced-motion: reduce`. Shimmer animation uses `motion-safe:animate-[...]` / `motion-reduce:hidden`. Under `prefers-reduced-motion`, the shimmer overlay is hidden entirely and the skeleton renders as a static muted shape.

---

# Progress

> Determinate linear and circular progress indicators with tokenized variants and sizing.

- id: `progress`
- type: primitive
- category: Feedback and status
- tags: primitive
- docs: https://glinui.com/docs/components/radix/progress
- markdown: https://glinui.com/md/progress.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add progress
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/progress.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Progress, ProgressCircle, CircularProgress, CONTROL_LEGACY_VARIANTS, CONTROL_SIZE_CLASSES, GlinProvider, GLIN_MOTIONS, GLIN_ENGINES } from "@glinui/ui"
```

## Usage

An upload card with one bar per file and a finished state.

```tsx
import { CheckCircle, CloudArrowUp, File } from "@phosphor-icons/react"
import {
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
  IconFrame,
  Progress
} from "@glinui/ui"

export function Demo() {
  const files = [
    { name: "brand-guidelines.pdf", size: "4.2 MB", value: 100 },
    { name: "homepage-v3.fig", size: "18.6 MB", value: 64 },
    { name: "launch-assets.zip", size: "52 MB", value: 23 }
  ]
  return (
    <Card className="w-full max-w-md">
      <CardHeader>
        <div className="flex items-center gap-3">
          <IconFrame tone="accent" size="lg"><CloudArrowUp aria-hidden className="size-5" /></IconFrame>
          <div>
            <CardTitle>Uploading 3 files</CardTitle>
            <CardDescription>About 40 seconds left</CardDescription>
          </div>
        </div>
      </CardHeader>
      <CardContent className="flex flex-col gap-4">
        {files.map((file) => (
          <div key={file.name} className="flex flex-col gap-2">
            <div className="flex items-center justify-between gap-3 text-sm">
              <span className="flex min-w-0 items-center gap-2">
                {file.value === 100 ? (
                  <CheckCircle aria-hidden weight="fill" className="size-4 shrink-0 text-[var(--tone-success)]" />
                ) : (
                  <File aria-hidden className="size-4 shrink-0 text-[var(--color-muted)]" />
                )}
                <span className="truncate font-medium">{file.name}</span>
              </span>
              <span className="shrink-0 tabular-nums text-[var(--color-muted)]">{file.value}%</span>
            </div>
            <Progress aria-label={`Uploading ${file.name}`} value={file.value} size="sm" />
          </div>
        ))}
      </CardContent>
    </Card>
  )
}
```

### Onboarding steps

A circular summary, a bar and a checklist share one value.

```tsx
import { CheckCircle } from "@phosphor-icons/react"
import {
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
  Progress,
  ProgressCircle
} from "@glinui/ui"

export function Demo() {
  const steps = [
    { label: "Create workspace", done: true },
    { label: "Invite your team", done: true },
    { label: "Connect a repository", done: false },
    { label: "Ship your first deploy", done: false }
  ]
  const done = steps.filter((step) => step.done).length
  return (
    <Card className="w-full max-w-sm">
      <CardHeader>
        <div className="flex items-center justify-between gap-4">
          <div>
            <CardTitle>Get started</CardTitle>
            <CardDescription>{done} of {steps.length} steps complete</CardDescription>
          </div>
          <ProgressCircle value={(done / steps.length) * 100} size="lg" showValue aria-label="Onboarding progress" />
        </div>
      </CardHeader>
      <CardContent className="flex flex-col gap-3">
        <Progress aria-label="Onboarding progress" value={(done / steps.length) * 100} />
        <ul className="flex flex-col gap-2 text-sm">
          {steps.map((step) => (
            <li key={step.label} className="flex items-center gap-2">
              <CheckCircle
                aria-hidden
                weight={step.done ? "fill" : "regular"}
                className={step.done ? "size-4 text-[var(--tone-success)]" : "size-4 text-[var(--color-muted)]"}
              />
              <span className={step.done ? "text-[var(--color-muted)] line-through" : "font-medium"}>{step.label}</span>
            </li>
          ))}
        </ul>
      </CardContent>
    </Card>
  )
}
```

### Variants

```tsx
import { Progress } from "@glinui/ui"

export function Demo() {
  return (
    <div className="space-y-3">
      <Progress variant="glinr" value={30} aria-label="glinr" />
      <Progress variant="solid" value={38} aria-label="solid" />
      <Progress variant="plain" value={46} aria-label="plain" />
      <Progress variant="soft" value={54} aria-label="soft" />
      <Progress variant="outline" value={62} aria-label="outline" />
      <Progress variant="ghost" value={70} aria-label="ghost" />
      <Progress variant="gradient" value={78} aria-label="gradient" />
    </div>
  )
}
```

## Props

### ProgressCircleProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `cap?` | `"round" \| "square" \| "butt"` | `"round"` |  |
| `formatValue?` | `(value: number) => React.ReactNode` |  |  |
| `indeterminate?` | `boolean` | `false` |  |
| `showValue?` | `boolean` | `true` |  |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from progressCircleVariants. |
| `strokeWidth?` | `number` | `4` |  |
| `value?` | `number` |  |  |
| `variant?` | `ControlVariantProp` |  |  |

### ProgressProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `indeterminate?` | `boolean` | `false` | Render loading state without aria-valuenow and fixed width indicator. |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from progressVariants. |
| `value?` | `number` |  | Current progress value from 0 to 100. |
| `variant?` | `ControlVariantProp` |  | Look. Omit to follow the ambient design style (glinr = inset track, accent fill). Also: solid, plain, soft, outline, ghost, gradient, gla... |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Built on Radix Progress with `role="progressbar"`.
- Provide `aria-label` for screen readers.
- Root uses Radix Progress semantics with `role="progressbar"`.
- Circular variant also exposes `role="progressbar"` with proper value attrs.
- Provide `aria-label` or external label for non-visual users.
- Values are clamped between `0` and `100`.

ARIA:

- `role="progressbar"`
- `aria-valuenow`
- `aria-valuemin`
- `aria-valuemax`

- Reduced motion: Width transition respects `prefers-reduced-motion` via `motion-reduce:transition-none`. Width transitions are disabled when `prefers-reduced-motion` is enabled.

---

# Empty

> Empty state with media, title, description, and action slots.

- id: `empty`
- type: primitive
- category: Feedback and status
- tags: primitive
- docs: https://glinui.com/docs/components/radix/empty
- markdown: https://glinui.com/md/empty.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add empty
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/empty.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Empty, EmptyHeader, EmptyMedia, EmptyTitle, EmptyDescription, EmptyContent, SURFACE_VARIANTS, SURFACE_TONES } from "@glinui/ui"
```

## Usage

An inbox zero state with a primary and a secondary action.

```tsx
import { Tray } from "@phosphor-icons/react"
import {
  Button,
  Empty,
  EmptyContent,
  EmptyDescription,
  EmptyHeader,
  EmptyMedia,
  EmptyTitle
} from "@glinui/ui"

export function Demo() {
  return (
    <Empty className="w-full max-w-lg">
      <EmptyHeader>
        <EmptyMedia variant="icon"><Tray aria-hidden /></EmptyMedia>
        <EmptyTitle>Inbox zero</EmptyTitle>
        <EmptyDescription>You have answered every conversation. New messages will show up here.</EmptyDescription>
      </EmptyHeader>
      <EmptyContent>
        <div className="flex flex-wrap justify-center gap-2">
          <Button>Compose message</Button>
          <Button variant="outline">View archive</Button>
        </div>
      </EmptyContent>
    </Empty>
  )
}
```

### Variants

Every vocabulary variant on the default tone. Omit variant to follow the ambient design style.

```tsx
import { Empty, EmptyDescription, EmptyHeader, EmptyTitle } from "@glinui/ui"

export function EmptyVariantsDemo() {
  return (
    <div className="grid gap-4 md:grid-cols-2">
      <Empty variant="glinr"><EmptyHeader><EmptyTitle>glinr</EmptyTitle><EmptyDescription>No items yet.</EmptyDescription></EmptyHeader></Empty>
      <Empty variant="solid"><EmptyHeader><EmptyTitle>solid</EmptyTitle><EmptyDescription>No items yet.</EmptyDescription></EmptyHeader></Empty>
      <Empty variant="plain"><EmptyHeader><EmptyTitle>plain</EmptyTitle><EmptyDescription>No items yet.</EmptyDescription></EmptyHeader></Empty>
      <Empty variant="soft"><EmptyHeader><EmptyTitle>soft</EmptyTitle><EmptyDescription>No items yet.</EmptyDescription></EmptyHeader></Empty>
      <Empty variant="outline"><EmptyHeader><EmptyTitle>outline</EmptyTitle><EmptyDescription>No items yet.</EmptyDescription></EmptyHeader></Empty>
      <Empty variant="ghost"><EmptyHeader><EmptyTitle>ghost</EmptyTitle><EmptyDescription>No items yet.</EmptyDescription></EmptyHeader></Empty>
      <Empty variant="gradient"><EmptyHeader><EmptyTitle>gradient</EmptyTitle><EmptyDescription>No items yet.</EmptyDescription></EmptyHeader></Empty>
    </div>
  )
}
```

### No results

A dashed empty state that offers a way back.

```tsx
import { MagnifyingGlass, Plus, X } from "@phosphor-icons/react"
import {
  Button,
  Empty,
  EmptyContent,
  EmptyDescription,
  EmptyHeader,
  EmptyMedia,
  EmptyTitle
} from "@glinui/ui"

export function Demo() {
  return (
    <Empty variant="dashed" className="w-full max-w-lg">
      <EmptyHeader>
        <EmptyMedia variant="icon"><MagnifyingGlass aria-hidden /></EmptyMedia>
        <EmptyTitle>No results for "quarterly report"</EmptyTitle>
        <EmptyDescription>Check the spelling, remove a filter, or search by project name instead.</EmptyDescription>
      </EmptyHeader>
      <EmptyContent>
        <div className="flex flex-wrap justify-center gap-2">
          <Button variant="outline" size="sm">
            <X aria-hidden className="size-4" />
            Clear filters
          </Button>
          <Button size="sm">
            <Plus aria-hidden className="size-4" />
            New document
          </Button>
        </div>
      </EmptyContent>
    </Empty>
  )
}
```

## Props

### EmptyMediaProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant?` | `"default" \| "icon"` | `"default"` | Variant option from emptyMediaVariants. |

### EmptyProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tone?` | `SurfaceTone` |  |  |
| `variant?` | `SurfaceVariant \| "dashed" \| "default" \| "raised" \| "frosted"` |  | Visual variant. Omit for the ambient design style (glinr: lift shell; plain: shadcn dashed block). Vocabulary: glinr, solid, plain, soft,... |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`, `icon`, `dashed`, `raised`, `frosted`.

## Accessibility

- Plain content container; headings and links inside keep their native semantics.
- Decorative icons should be `aria-hidden`.
- Use an actual heading element via `EmptyTitle` content when the empty state needs to appear in the document outline.

Keyboard:

| Key | Action |
| --- | --- |
| Tab | Moves through actions placed in EmptyContent. |

- Reduced motion: Static component with no motion.

---

# Status Dot

> Colored status indicator with optional label and pulse state.

- id: `status-dot`
- type: primitive
- category: Feedback and status
- tags: primitive
- docs: https://glinui.com/docs/components/radix/status-dot
- markdown: https://glinui.com/md/status-dot.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add status-dot
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/status-dot.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { StatusDot } from "@glinui/ui"
```

## Usage

A service status list. Pulse marks states that need attention.

```tsx
import {
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
  Separator,
  StatusDot
} from "@glinui/ui"

export function Demo() {
  const services = [
    { name: "API", note: "Operational", status: "success" as const },
    { name: "Dashboard", note: "Operational", status: "success" as const },
    { name: "Webhooks", note: "Degraded, retrying", status: "warning" as const, pulse: true },
    { name: "Billing", note: "Major outage", status: "danger" as const, pulse: true },
    { name: "Docs", note: "Maintenance at 02:00 UTC", status: "info" as const },
    { name: "Legacy SDK", note: "Not monitored", status: "neutral" as const }
  ]
  return (
    <Card className="w-full max-w-md">
      <CardHeader>
        <CardTitle>System status</CardTitle>
        <CardDescription>Updated 2 minutes ago</CardDescription>
      </CardHeader>
      <CardContent className="flex flex-col">
        {services.map((service, index) => (
          <div key={service.name}>
            {index > 0 ? <Separator /> : null}
            <div className="flex items-center justify-between gap-3 py-3">
              <span className="text-sm font-medium">{service.name}</span>
              <StatusDot status={service.status} pulse={service.pulse} label={service.note} />
            </div>
          </div>
        ))}
      </CardContent>
    </Card>
  )
}
```

### Sizes and states

Three sizes and every status.

```tsx
import { StatusDot } from "@glinui/ui"

export function Demo() {
  return (
    <div className="flex flex-wrap items-center gap-x-8 gap-y-4">
      {(["sm", "md", "lg"] as const).map((size) => (
        <StatusDot key={size} size={size} status="success" label={`Size ${size}`} />
      ))}
      {(["neutral", "info", "success", "warning", "danger"] as const).map((status) => (
        <StatusDot key={status} status={status} pulse={status === "danger"} label={status} />
      ))}
    </div>
  )
}
```

### Pulse

Enable `pulse` to add a `motion-safe:animate-pulse` animation to the dot. Useful for active or live states.

```tsx
import { StatusDot } from "@glinui/ui"

export function StatusDotPulseDemo() {
  return (
    <div className="flex flex-col gap-2">
      <StatusDot status="success" label="Live" pulse />
      <StatusDot status="danger" label="Critical" pulse />
    </div>
  )
}
```

## Props

### StatusDotProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label?` | `string` |  |  |
| `pulse?` | `"true" \| "false"` | `false` | Variant option from dotVariants. |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from statusDotVariants. |
| `status?` | `"neutral" \| "info" \| "success" \| "warning" \| "danger"` | `"neutral"` | Variant option from dotVariants. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Pair status color with text for non-color-only communication.
- Optional pulse animation is reduced-motion safe.
- The dot `<span>` is `aria-hidden="true"`, color alone does not convey meaning to assistive technologies.
- Always supply a `label` or `children` describing the status in plain text.
- When using `StatusDot` inside a live region (e.g. a dashboard that polls for updates), wrap it in `role="status"` with `aria-live="polite"`.

ARIA:

- `aria-live="polite"` when representing dynamic system state

- Reduced motion: Pulse animation uses `motion-safe` and disables with reduced-motion preferences. The `pulse` animation uses `motion-safe:animate-pulse`. Under `prefers-reduced-motion: reduce`, the dot renders as a static colored circle with no animation.

---

# Badge

> Compact status indicator for labels, states, and counts.

- id: `badge`
- type: primitive
- category: Data display
- tags: primitive
- docs: https://glinui.com/docs/components/radix/badge
- markdown: https://glinui.com/md/badge.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add badge
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/badge.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Badge, SURFACE_VARIANTS, SURFACE_TONES, SURFACE_ELEVATIONS, SURFACE_VARIANT_ALIASES, STYLE_DEFAULT_VARIANT, GlinProvider, GLIN_MOTIONS } from "@glinui/ui"
```

## Usage

A filter toolbar above a list of pull requests with status pills.

```tsx
import { useState } from "react"
import { GitBranch } from "@phosphor-icons/react"
import {
  Badge,
  Button,
  Item,
  ItemActions,
  ItemContent,
  ItemDescription,
  ItemGroup,
  ItemMedia,
  ItemTitle
} from "@glinui/ui"

export function Demo() {
  const [status, setStatus] = useState("All")
  const filters = ["All", "Open", "In review", "Merged"]
  return (
    <div className="flex w-full max-w-2xl flex-col gap-4">
      <div role="group" aria-label="Filter pull requests" className="flex flex-wrap items-center gap-2">
        {filters.map((filter) => (
          <Button
            key={filter}
            size="sm"
            variant={status === filter ? "solid" : "outline"}
            aria-pressed={status === filter}
            onClick={() => setStatus(filter)}
          >
            {filter}
          </Button>
        ))}
      </div>
      <ItemGroup>
        <Item size="sm">
          <ItemMedia variant="icon"><GitBranch aria-hidden /></ItemMedia>
          <ItemContent>
            <ItemTitle>Add CSV export to reports</ItemTitle>
            <ItemDescription>#482 opened by Priya Nair</ItemDescription>
          </ItemContent>
          <ItemActions><Badge tone="success" variant="soft" dot>Open</Badge></ItemActions>
        </Item>
        <Item size="sm">
          <ItemMedia variant="icon"><GitBranch aria-hidden /></ItemMedia>
          <ItemContent>
            <ItemTitle>Fix timezone drift in schedules</ItemTitle>
            <ItemDescription>#479 opened by Diego Alvarez</ItemDescription>
          </ItemContent>
          <ItemActions><Badge tone="warning" variant="soft" dot dotTone="accent">In review</Badge></ItemActions>
        </Item>
        <Item size="sm">
          <ItemMedia variant="icon"><GitBranch aria-hidden /></ItemMedia>
          <ItemContent>
            <ItemTitle>Upgrade to Node 22</ItemTitle>
            <ItemDescription>#471 opened by Hana Sato</ItemDescription>
          </ItemContent>
          <ItemActions><Badge tone="accent" variant="soft">Merged</Badge></ItemActions>
        </Item>
      </ItemGroup>
    </div>
  )
}
```

### Variants

Every vocabulary variant on the default tone. Omit variant to follow the ambient design style.

```tsx
import { Badge } from "@glinui/ui"

export function BadgeVariantsDemo() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <Badge variant="glinr">glinr</Badge>
      <Badge variant="solid">solid</Badge>
      <Badge variant="plain">plain</Badge>
      <Badge variant="soft">soft</Badge>
      <Badge variant="outline">outline</Badge>
      <Badge variant="ghost">ghost</Badge>
      <Badge variant="gradient">gradient</Badge>
    </div>
  )
}
```

### Sizes, dots and icons

Sizes, status dots and leading icons.

```tsx
import { Lock, ShieldCheck } from "@phosphor-icons/react"
import { Badge } from "@glinui/ui"

export function Demo() {
  return (
    <div className="flex w-full max-w-xl flex-col gap-5">
      <div className="flex flex-wrap items-center gap-2">
        <Badge size="sm">Small</Badge>
        <Badge size="md">Medium</Badge>
        <Badge size="lg">Large</Badge>
        <Badge tone="accent" variant="solid">New</Badge>
        <Badge tone="danger" variant="outline">Blocked</Badge>
      </div>
      <div className="flex flex-wrap items-center gap-2">
        <Badge variant="soft" tone="success" dot>Live</Badge>
        <Badge variant="soft" tone="warning" dot dotTone="accent">Pending</Badge>
        <Badge variant="soft" tone="danger" dot dotTone="live">Failed</Badge>
        <Badge variant="soft" tone="info">
          <ShieldCheck aria-hidden className="mr-1 size-3.5" />
          Verified
        </Badge>
        <Badge variant="outline">
          <Lock aria-hidden className="mr-1 size-3.5" />
          Private
        </Badge>
      </div>
    </div>
  )
}
```

## Props

### BadgeProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `asChild?` | `boolean` | `false` | Render the child element (for example an anchor) with badge styling. |
| `dot?` | `boolean` | `false` | Show a glowing status dot before the content. |
| `dotTone?` | `BadgeDotTone` | `"ok"` | Dot color. |
| `size?` | `"sm" \| "md" \| "lg"` |  |  |
| `tone?` | `SurfaceTone` |  | Colour tone for the vocabulary variants. |
| `variant?` | `SurfaceVariant \| ExtraVariant \| "default" \| "primary" \| "secondary" \| "destructive" \| "success" \| "w...` |  | Visual variant. Omit for the ambient design style (glinr by default). Vocabulary: glinr, solid, plain, soft, outline, ghost, gradient, gl... |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`, `primary`, `secondary`, `destructive`, `success`, `warning`, `info`, `raised`, `frosted`.

## Accessibility

- Renders as `<span>` -- decorative by default.
- Add `role="status"` if badge conveys live state.
- Use badge text that remains understandable out of context.
- Do not rely on color-only meaning.

ARIA:

- Decorative by default
- Add `role="status"` for live state badges

- Reduced motion: No animation dependencies. Badge is static and motion-independent.

---

# Chip

> Compact pill-style tag for statuses and lightweight metadata.

- id: `chip`
- type: primitive
- category: Data display
- tags: primitive
- docs: https://glinui.com/docs/components/radix/chip
- markdown: https://glinui.com/md/chip.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add chip
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/chip.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Chip, SURFACE_VARIANTS, SURFACE_TONES, SURFACE_ELEVATIONS, SURFACE_VARIANT_ALIASES, STYLE_DEFAULT_VARIANT, GlinProvider, GLIN_MOTIONS } from "@glinui/ui"
```

## Usage

Toggleable filter chips. Wrap each chip in a button and set aria-pressed.

```tsx
import { useState } from "react"
import { Check } from "@phosphor-icons/react"
import { Chip } from "@glinui/ui"

export function Demo() {
  const options = ["Design", "Engineering", "Marketing", "Support", "Finance", "People"]
  const [selected, setSelected] = useState<string[]>(["Design", "Engineering"])
  const toggle = (option: string) =>
    setSelected((current) => (current.includes(option) ? current.filter((item) => item !== option) : [...current, option]))
  return (
    <div className="flex w-full max-w-xl flex-col gap-4">
      <div className="flex items-center justify-between gap-3">
        <span id="team-filter" className="text-sm font-medium">Teams</span>
        <span className="text-xs text-[var(--color-muted)]">{selected.length} selected</span>
      </div>
      <div role="group" aria-labelledby="team-filter" className="flex flex-wrap gap-2">
        {options.map((option) => {
          const active = selected.includes(option)
          return (
            <button
              key={option}
              type="button"
              aria-pressed={active}
              onClick={() => toggle(option)}
              className="rounded-full focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-accent)] focus-visible:ring-offset-2"
            >
              <Chip variant={active ? "solid" : "outline"} tone={active ? "accent" : "neutral"} size="lg" className="cursor-pointer gap-1.5">
                {active ? <Check aria-hidden weight="bold" className="size-3.5" /> : null}
                {option}
              </Chip>
            </button>
          )
        })}
      </div>
    </div>
  )
}
```

### Variants

Every vocabulary variant on the default tone. Omit variant to follow the ambient design style.

```tsx
import { Chip } from "@glinui/ui"

export function ChipVariantsDemo() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <Chip variant="glinr">glinr</Chip>
      <Chip variant="solid">solid</Chip>
      <Chip variant="plain">plain</Chip>
      <Chip variant="soft">soft</Chip>
      <Chip variant="outline">outline</Chip>
      <Chip variant="ghost">ghost</Chip>
      <Chip variant="gradient">gradient</Chip>
    </div>
  )
}
```

### Tones and sizes

Tag chips in every tone, and three sizes.

```tsx
import { Chip } from "@glinui/ui"

export function Demo() {
  return (
    <div className="flex w-full max-w-xl flex-col gap-4">
      <div className="flex flex-wrap items-center gap-2">
        <Chip variant="soft" tone="accent">design-system</Chip>
        <Chip variant="soft" tone="info">react</Chip>
        <Chip variant="soft" tone="success">accessibility</Chip>
        <Chip variant="soft" tone="warning">needs-review</Chip>
        <Chip variant="soft" tone="danger">breaking</Chip>
      </div>
      <div className="flex flex-wrap items-center gap-2">
        <Chip size="sm">Small</Chip>
        <Chip size="md">Medium</Chip>
        <Chip size="lg">Large</Chip>
      </div>
    </div>
  )
}
```

## Props

### ChipProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size?` | `"sm" \| "md" \| "lg"` |  |  |
| `tone?` | `SurfaceTone` |  | Colour tone. Tinted faces are built with color-mix on the surface tokens. |
| `variant?` | `SurfaceVariant \| "default" \| "primary" \| "secondary" \| "destructive" \| "success" \| "warning" \| "info...` |  | Visual variant. Omit for the ambient design style (glinr: raised pill with a hairline ring). Vocabulary: glinr, solid, plain, soft, outli... |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`, `primary`, `secondary`, `destructive`, `success`, `warning`, `info`, `raised`, `frosted`.

## Accessibility

- Non-interactive status label element by default.
- Use `aria-label` when chip meaning is not explicit from text.
- Use descriptive text that conveys meaning without relying on color alone.
- Pair `tone` with a text label or icon label so screen readers communicate intent.
- If the chip is interactive, wrap it in a `<button>` or use an anchor, Chip itself is a display element.
- Avoid using Chip as the sole status indicator; supplement with accessible text where needed.

ARIA:

- `role="status"` optional for live status chips

- Reduced motion: Chip visual transitions are color-only and disabled with reduced motion. Chip is a static display primitive with no animation. No reduced-motion considerations apply.

---

# Table

> Composable data table with semantic sections and glass variant support.

- id: `table`
- type: primitive
- category: Data display
- tags: primitive
- docs: https://glinui.com/docs/components/radix/table
- markdown: https://glinui.com/md/table.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add table
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/table.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Table, TableHeader, TableBody, TableFooter, TableRow, TableHead, TableCell, TableCaption } from "@glinui/ui"
```

## Usage

An invoices table with a sortable header hint, avatars, status badges and a row actions menu.

```tsx
import { ArrowsDownUp, DotsThree, Download, Envelope, Trash } from "@phosphor-icons/react"
import {
  Avatar,
  Badge,
  Button,
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
  Table,
  TableBody,
  TableCell,
  TableHead,
  TableHeader,
  TableRow
} from "@glinui/ui"

export function Demo() {
  const invoices = [
    { id: "INV-2041", client: "Northwind Studio", initials: "NS", amount: "$1,240.00", status: "Paid", due: "Oct 02" },
    { id: "INV-2040", client: "Fabrikam Labs", initials: "FL", amount: "$3,890.00", status: "Pending", due: "Oct 14" },
    { id: "INV-2039", client: "Contoso Health", initials: "CH", amount: "$620.50", status: "Overdue", due: "Sep 21" },
    { id: "INV-2038", client: "Tailspin Toys", initials: "TT", amount: "$2,115.00", status: "Paid", due: "Sep 18" }
  ]
  const tone = { Paid: "success", Pending: "warning", Overdue: "danger" } as const
  return (
    <div className="w-full max-w-3xl">
      <Table>
        <TableHeader>
          <TableRow>
            <TableHead>
              <button type="button" className="inline-flex items-center gap-1 font-semibold">
                Invoice
                <ArrowsDownUp aria-hidden className="size-3.5 text-[var(--color-muted)]" />
              </button>
            </TableHead>
            <TableHead>Client</TableHead>
            <TableHead>Status</TableHead>
            <TableHead align="right">Amount</TableHead>
            <TableHead><span className="sr-only">Actions</span></TableHead>
          </TableRow>
        </TableHeader>
        <TableBody>
          {invoices.map((invoice) => (
            <TableRow key={invoice.id}>
              <TableCell>
                <div className="flex flex-col">
                  <span className="font-medium">{invoice.id}</span>
                  <span className="text-xs text-[var(--color-muted)]">Due {invoice.due}</span>
                </div>
              </TableCell>
              <TableCell>
                <div className="flex items-center gap-2">
                  <Avatar size="xs" fallback={invoice.initials} />
                  <span>{invoice.client}</span>
                </div>
              </TableCell>
              <TableCell>
                <Badge variant="soft" tone={tone[invoice.status as keyof typeof tone]} dot>{invoice.status}</Badge>
              </TableCell>
              <TableCell align="right" className="tabular-nums">{invoice.amount}</TableCell>
              <TableCell align="right">
                <DropdownMenu>
                  <DropdownMenuTrigger asChild>
                    <Button variant="ghost" size="sm" aria-label={`Actions for ${invoice.id}`}>
                      <DotsThree aria-hidden weight="bold" className="size-4" />
                    </Button>
                  </DropdownMenuTrigger>
                  <DropdownMenuContent align="end">
                    <DropdownMenuItem><Download aria-hidden className="size-4" />Download PDF</DropdownMenuItem>
                    <DropdownMenuItem><Envelope aria-hidden className="size-4" />Send reminder</DropdownMenuItem>
                    <DropdownMenuSeparator />
                    <DropdownMenuItem><Trash aria-hidden className="size-4" />Void invoice</DropdownMenuItem>
                  </DropdownMenuContent>
                </DropdownMenu>
              </TableCell>
            </TableRow>
          ))}
        </TableBody>
      </Table>
    </div>
  )
}
```

### Variants

Every vocabulary variant on the default tone. Omit variant to follow the ambient design style.

```tsx
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@glinui/ui"

export function TableVariantsDemo() {
  return (
    <div className="grid gap-4 md:grid-cols-2">
      <Table variant="glinr" containerClassName="w-full"><TableHeader><TableRow><TableHead>Name</TableHead><TableHead>Status</TableHead></TableRow></TableHeader><TableBody><TableRow><TableCell>Glin UI</TableCell><TableCell>Active</TableCell></TableRow></TableBody></Table>
      <Table variant="solid" containerClassName="w-full"><TableHeader><TableRow><TableHead>Name</TableHead><TableHead>Status</TableHead></TableRow></TableHeader><TableBody><TableRow><TableCell>Glin UI</TableCell><TableCell>Active</TableCell></TableRow></TableBody></Table>
      <Table variant="plain" containerClassName="w-full"><TableHeader><TableRow><TableHead>Name</TableHead><TableHead>Status</TableHead></TableRow></TableHeader><TableBody><TableRow><TableCell>Glin UI</TableCell><TableCell>Active</TableCell></TableRow></TableBody></Table>
      <Table variant="soft" containerClassName="w-full"><TableHeader><TableRow><TableHead>Name</TableHead><TableHead>Status</TableHead></TableRow></TableHeader><TableBody><TableRow><TableCell>Glin UI</TableCell><TableCell>Active</TableCell></TableRow></TableBody></Table>
      <Table variant="outline" containerClassName="w-full"><TableHeader><TableRow><TableHead>Name</TableHead><TableHead>Status</TableHead></TableRow></TableHeader><TableBody><TableRow><TableCell>Glin UI</TableCell><TableCell>Active</TableCell></TableRow></TableBody></Table>
      <Table variant="ghost" containerClassName="w-full"><TableHeader><TableRow><TableHead>Name</TableHead><TableHead>Status</TableHead></TableRow></TableHeader><TableBody><TableRow><TableCell>Glin UI</TableCell><TableCell>Active</TableCell></TableRow></TableBody></Table>
      <Table variant="gradient" containerClassName="w-full"><TableHeader><TableRow><TableHead>Name</TableHead><TableHead>Status</TableHead></TableRow></TableHeader><TableBody><TableRow><TableCell>Glin UI</TableCell><TableCell>Active</TableCell></TableRow></TableBody></Table>
    </div>
  )
}
```

### In a layout

A striped compact table inside a card with an export action and pagination.

```tsx
import { CaretLeft, CaretRight, Download } from "@phosphor-icons/react"
import {
  Badge,
  Button,
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
  Table,
  TableBody,
  TableCell,
  TableHead,
  TableHeader,
  TableRow
} from "@glinui/ui"

export function Demo() {
  const rows = [
    { name: "Glin UI", owner: "Maya Kovacs", visits: "48,210", status: "Live" },
    { name: "Docs", owner: "Jonas Okafor", visits: "21,904", status: "Live" },
    { name: "Registry", owner: "Priya Nair", visits: "9,318", status: "Building" },
    { name: "Playground", owner: "Diego Alvarez", visits: "2,044", status: "Paused" }
  ]
  const tone = { Live: "success", Building: "warning", Paused: "neutral" } as const
  return (
    <Card className="w-full max-w-3xl">
      <CardHeader>
        <div className="flex flex-wrap items-center justify-between gap-3">
          <div>
            <CardTitle>Projects</CardTitle>
            <CardDescription>Traffic over the last 30 days.</CardDescription>
          </div>
          <Button size="sm" variant="outline">
            <Download aria-hidden className="size-4" />
            Export
          </Button>
        </div>
      </CardHeader>
      <CardContent className="flex flex-col gap-4">
        <Table striped size="sm">
          <TableHeader>
            <TableRow>
              <TableHead>Project</TableHead>
              <TableHead>Owner</TableHead>
              <TableHead>Status</TableHead>
              <TableHead align="right">Visits</TableHead>
            </TableRow>
          </TableHeader>
          <TableBody>
            {rows.map((row) => (
              <TableRow key={row.name}>
                <TableCell className="font-medium">{row.name}</TableCell>
                <TableCell>{row.owner}</TableCell>
                <TableCell><Badge variant="soft" tone={tone[row.status as keyof typeof tone]}>{row.status}</Badge></TableCell>
                <TableCell align="right" className="tabular-nums">{row.visits}</TableCell>
              </TableRow>
            ))}
          </TableBody>
        </Table>
        <div className="flex items-center justify-between gap-3 text-sm text-[var(--color-muted)]">
          <span>Showing 1 to 4 of 12</span>
          <div className="flex items-center gap-2">
            <Button size="sm" variant="outline" disabled aria-label="Previous page"><CaretLeft aria-hidden className="size-4" /></Button>
            <Button size="sm" variant="outline" aria-label="Next page"><CaretRight aria-hidden className="size-4" /></Button>
          </div>
        </div>
      </CardContent>
    </Card>
  )
}
```

## Props

### TableCellProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align?` | `"left" \| "center" \| "right"` | `"left"` |  |
| `sticky?` | `boolean` | `false` |  |
| `truncate?` | `boolean` | `false` |  |

### TableHeadProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align?` | `"left" \| "center" \| "right"` | `"left"` |  |
| `sticky?` | `boolean` | `false` |  |

### TableProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `containerClassName?` | `string` |  |  |
| `grid?` | `boolean` | `false` |  |
| `interactive?` | `boolean` | `true` |  |
| `layout?` | `"auto" \| "fixed"` | `"auto"` |  |
| `noWrap?` | `boolean` | `false` |  |
| `rowDividers?` | `boolean` | `true` |  |
| `size?` | `"sm" \| "md" \| "lg"` |  |  |
| `stickyFirstColumn?` | `boolean` | `false` |  |
| `stickyHeader?` | `boolean` | `false` |  |
| `striped?` | `boolean` | `false` |  |
| `variant?` | `SurfaceVariant \| "liquid" \| "matte" \| "lift" \| "default" \| "raised" \| "frosted"` |  | Visual variant. Omit for the ambient design style (glinr: lift wrapper with a raised header strip; plain: shadcn table). Vocabulary: glin... |
| `wide?` | `boolean \| string` | `false` | Force a minimum table width so the wrapper scrolls horizontally on narrow screens. |

### TableRowProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tone?` | `TableRowTone` | `"default"` |  |

### YesNoProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `noLabel?` | `string` | `"No"` | Screen reader text for the no state. |
| `value` | `boolean` |  | True renders a check, false renders a minus. |
| `yesLabel?` | `string` | `"Yes"` | Screen reader text for the yes state. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `liquid`, `matte`, `lift`, `default`, `raised`, `frosted`.

## Accessibility

- Native `<table>` semantics with proper `<thead>`/`<tbody>` structure.
- Use `<th>` for column headers.
- Sticky headers preserve semantics because structure remains native.
- Uses semantic table elements (`table`, `thead`, `tbody`, `th`, `td`, `caption`).
- Keep column headers descriptive for screen reader table navigation.
- Use `TableCaption` to provide context when needed.

ARIA:

- Native table semantics with `<th scope>`

- Reduced motion: Row hover color transitions use motion-safe classes with reduced-motion fallback. Row hover transitions respect reduced-motion preferences.

---

# Data Table

> Feature-rich table wrapper with search, sorting, pagination, selection, and column controls.

- id: `data-table`
- type: primitive
- category: Data display
- tags: primitive
- docs: https://glinui.com/docs/components/radix/data-table
- markdown: https://glinui.com/md/data-table.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add data-table
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/data-table.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { DataTable, Table, TableHeader, TableBody, TableFooter, TableRow, TableHead, TableCell } from "@glinui/ui"
```

## Usage

A users table with status filters, search, sorting, selection and pagination.

```tsx
import { useState } from "react"
import { Avatar, Badge, Button, DataTable } from "@glinui/ui"

export function Demo() {
  type User = { id: string; name: string; email: string; role: string; status: string; seats: number }
  const users: User[] = [
    { id: "u1", name: "Maya Kovacs", email: "maya@northwind.io", role: "Owner", status: "Active", seats: 12 },
    { id: "u2", name: "Jonas Okafor", email: "jonas@northwind.io", role: "Admin", status: "Active", seats: 8 },
    { id: "u3", name: "Priya Nair", email: "priya@fabrikam.dev", role: "Editor", status: "Invited", seats: 4 },
    { id: "u4", name: "Diego Alvarez", email: "diego@contoso.com", role: "Viewer", status: "Suspended", seats: 1 },
    { id: "u5", name: "Hana Sato", email: "hana@tailspin.jp", role: "Editor", status: "Active", seats: 6 },
    { id: "u6", name: "Lena Brandt", email: "lena@fabrikam.dev", role: "Viewer", status: "Active", seats: 2 },
    { id: "u7", name: "Tomas Reyes", email: "tomas@contoso.com", role: "Admin", status: "Invited", seats: 5 }
  ]
  const [filter, setFilter] = useState("All")
  const tone = { Active: "success", Invited: "warning", Suspended: "danger" } as const
  const rows = filter === "All" ? users : users.filter((user) => user.status === filter)
  return (
    <div className="flex w-full max-w-3xl flex-col gap-3">
      <div role="group" aria-label="Filter by status" className="flex flex-wrap gap-2">
        {["All", "Active", "Invited", "Suspended"].map((option) => (
          <Button
            key={option}
            size="sm"
            variant={filter === option ? "solid" : "outline"}
            aria-pressed={filter === option}
            onClick={() => setFilter(option)}
          >
            {option}
          </Button>
        ))}
      </div>
      <DataTable
        columns={[
          {
            id: "name",
            header: "User",
            accessor: "name",
            sortable: true,
            searchable: true,
            cell: ({ row }) => (
              <div className="flex items-center gap-3">
                <Avatar size="sm" fallback={row.name.split(" ").map((part) => part[0]).join("")} />
                <div className="flex flex-col">
                  <span className="font-medium">{row.name}</span>
                  <span className="text-xs text-[var(--color-muted)]">{row.email}</span>
                </div>
              </div>
            )
          },
          { id: "role", header: "Role", accessor: "role", sortable: true },
          {
            id: "status",
            header: "Status",
            accessor: "status",
            cell: ({ row }) => (
              <Badge variant="soft" tone={tone[row.status as keyof typeof tone]} dot>{row.status}</Badge>
            )
          },
          { id: "seats", header: "Seats", accessor: "seats", sortable: true, align: "right" }
        ]}
        data={rows}
        getRowId={(row) => row.id}
        searchable
        searchPlaceholder="Search users"
        selectable
        pageSize={5}
      />
    </div>
  )
}
```

### Grid and sticky header

```tsx
import { Badge, DataTable } from "@glinui/ui"

const columns = [
  { id: "project", header: "Project", accessor: "project" },
  {
    id: "status",
    header: "Status",
    accessor: "status",
    cell: ({ value }) => <Badge variant={value === "Active" ? "soft" : "outline"}>{String(value)}</Badge>
  },
  { id: "mrr", header: "MRR", accessor: "mrr", align: "right" }
]

const data = [
  { id: "p1", project: "Glin UI", status: "Active", mrr: 18400 },
  { id: "p2", project: "Glin Docs", status: "Monitoring", mrr: 7920 },
  { id: "p3", project: "Registry", status: "Active", mrr: 12340 },
  { id: "p4", project: "CLI", status: "Paused", mrr: 2310 }
]

export function Demo() {
  return (
    <DataTable
      columns={columns}
      data={data}
      selectable
      striped
      stickyHeader
      grid
      variant="soft"
      pageSize={3}
      getRowId={(row) => row.id}
    />
  )
}
```

### Compact Board With Sticky Header

```tsx
import { DataTable } from "@glinui/ui"

export function DataTableCompactDemo() {
  return (
    <DataTable
      columns={[
        { id: "account", header: "Account", accessor: "account", sortable: true },
        { id: "stage", header: "Stage", accessor: "stage", sortable: true },
        { id: "owner", header: "Owner", accessor: "owner", sortable: true },
        { id: "arr", header: "ARR", accessor: "arr", sortable: true, align: "right" },
      ]}
      data={[
        { id: "op-4012", account: "Northwind", stage: "Qualified", owner: "Maya", arr: "$42,000" },
        { id: "op-4015", account: "Stellar Forge", stage: "Proposal", owner: "Ilya", arr: "$18,500" },
        { id: "op-4018", account: "Blue Harbor", stage: "Won", owner: "Rae", arr: "$63,200" },
        { id: "op-4021", account: "Arcadia Labs", stage: "Discovery", owner: "Nico", arr: "$11,900" },
        { id: "op-4022", account: "Halcyon", stage: "Qualified", owner: "Leah", arr: "$27,600" },
      ]}
      getRowId={(row) => row.id}
      variant="matte"
      size="sm"
      stickyHeader
      containerClassName="max-h-72"
      pageSize={5}
      searchable
    />
  )
}
```

## Props

### DataTableProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className?` | `string` |  |  |
| `columns` | `DataTableColumn<TData>[]` |  |  |
| `data` | `TData[]` |  |  |
| `emptyMessage?` | `string` | `"No results."` |  |
| `getRowId?` | `(row: TData, index: number) => string` |  |  |
| `onRowClick?` | `(row: TData) => void` |  |  |
| `onSelectionChange?` | `(rows: TData[]) => void` |  |  |
| `pageSize?` | `number` | `10` |  |
| `pageSizeOptions?` | `number[]` | `[10, 20, 50]` |  |
| `rowTone?` | `(row: TData) => TableRowTone` |  |  |
| `searchable?` | `boolean` | `true` |  |
| `searchPlaceholder?` | `string` | `"Search rows..."` |  |
| `selectable?` | `boolean` | `false` |  |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Built on semantic table primitives for screen reader compatibility.
- Sorting controls are keyboard-focusable buttons in header cells.
- Selection checkboxes provide explicit labels.
- Built on semantic table elements (`table`, `thead`, `tbody`, `th`, and `td`) for screen-reader compatibility.
- Keep column names concise and unique so assistive tech announces context clearly.

Keyboard:

| Key | Action |
| --- | --- |
| Tab | Move across toolbar, headers, and pagination controls. |
| Enter / Space | Activate sort, selection, and pagination controls. |

ARIA:

- `aria-label` for search and selection controls
- `role="checkbox"` for selectable rows
- Native table semantics from the base table primitive

- Reduced motion: Inherits reduced-motion behavior from Table and action/input primitives. DataTable inherits reduced-motion behavior from `Table`, `Input`, `Select`, and `Button`. Hover/focus transitions are non-essential and respect user preference settings.

---

# Counter

> Numeric badge that compacts overflow values like 99+.

- id: `counter`
- type: primitive
- category: Data display
- tags: primitive
- docs: https://glinui.com/docs/components/radix/counter
- markdown: https://glinui.com/md/counter.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add counter
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/counter.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Counter, SURFACE_VARIANTS, SURFACE_TONES, SURFACE_ELEVATIONS, SURFACE_VARIANT_ALIASES, STYLE_DEFAULT_VARIANT, GlinProvider, GLIN_MOTIONS } from "@glinui/ui"
```

## Usage

Counts in a mailbox navigation. Values above max show max+.

```tsx
import { Counter } from "@glinui/ui"

export function Demo() {
  const tabs = [
    { label: "Inbox", count: 12, tone: "accent" as const },
    { label: "Mentions", count: 3, tone: "danger" as const },
    { label: "Drafts", count: 0, tone: "neutral" as const },
    { label: "Archive", count: 248, tone: "neutral" as const }
  ]
  return (
    <div className="flex w-full max-w-sm flex-col gap-1 rounded-xl border border-[var(--line-soft)] p-2">
      {tabs.map((tab, index) => (
        <button
          key={tab.label}
          type="button"
          aria-current={index === 0 ? "page" : undefined}
          className="flex items-center justify-between gap-3 rounded-lg px-3 py-2 text-left text-sm font-medium hover:bg-[var(--surface-2)] aria-[current=page]:bg-[var(--surface-2)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-accent)]"
        >
          {tab.label}
          <Counter value={tab.count} tone={tab.tone} variant={tab.tone === "neutral" ? "soft" : "solid"} max={99} aria-label={`${tab.count} items`} />
        </button>
      ))}
    </div>
  )
}
```

### Variants

Every vocabulary variant on the default tone. Omit variant to follow the ambient design style.

```tsx
import { Counter } from "@glinui/ui"

export function CounterVariantsDemo() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <Counter variant="glinr" value={12} />
      <Counter variant="solid" value={12} />
      <Counter variant="plain" value={12} />
      <Counter variant="soft" value={12} />
      <Counter variant="outline" value={12} />
      <Counter variant="ghost" value={12} />
      <Counter variant="gradient" value={12} />
    </div>
  )
}
```

### Sizes and badges

Sizes, and counters on a button and an icon.

```tsx
import { Bell, Envelope } from "@phosphor-icons/react"
import { Button, Counter, IconFrame } from "@glinui/ui"

export function Demo() {
  return (
    <div className="flex flex-wrap items-center gap-6">
      <div className="flex items-center gap-2">
        <Counter value={4} size="sm" />
        <Counter value={42} size="md" />
        <Counter value={420} size="lg" />
      </div>
      <Button variant="outline" size="sm" className="gap-2">
        <Bell aria-hidden className="size-4" />
        Notifications
        <Counter value={7} tone="danger" variant="solid" size="sm" />
      </Button>
      <span className="relative inline-flex">
        <IconFrame size="lg"><Envelope aria-hidden className="size-5" /></IconFrame>
        <Counter value={128} max={99} tone="danger" variant="solid" size="sm" className="absolute -right-2 -top-2" aria-label="128 unread" />
      </span>
    </div>
  )
}
```

## Props

### CounterProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `max?` | `number` | `99` |  |
| `size?` | `"sm" \| "md" \| "lg"` |  |  |
| `tone?` | `SurfaceTone` |  |  |
| `value` | `number` |  |  |
| `variant?` | `SurfaceVariant \| "default" \| "primary" \| "secondary" \| "destructive" \| "success" \| "warning" \| "info...` |  | Visual variant. Omit for the ambient design style (glinr by default). |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`, `primary`, `secondary`, `destructive`, `success`, `warning`, `info`, `raised`, `frosted`.

## Accessibility

- Use `aria-label` to describe what the count represents.
- `Counter` should be accompanied by a visible label in its surrounding context (e.g., "Notifications: 12") so the number is not the sole conveyor of meaning.
- When used as a live notification badge, wrap the containing element with `aria-live="polite"` so screen readers announce value changes.
- The truncated `max+` format must be interpreted from context, add an `aria-label` to clarify if necessary (e.g., `aria-label="More than 99 notifications"`).
- Do not rely on the counter's color alone to communicate urgency; pair with surrounding labels.

ARIA:

- `aria-live="polite"` for dynamically updating counts

- Reduced motion: Counter updates are static by default with no animated value tweening. `Counter` is a static numeric display with no animation. No reduced-motion considerations apply.

---

# Number Ticker

> Animated number counter triggered by scroll visibility via IntersectionObserver.

- id: `number-ticker`
- type: signature
- category: Data display
- tags: signature
- docs: https://glinui.com/docs/components/number-ticker
- markdown: https://glinui.com/md/number-ticker.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add number-ticker
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/number-ticker.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { NumberTicker, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider } from "@glinui/ui"
```

## Usage

```tsx
import { NumberTicker } from "@glinui/ui"

export function NumberTickerDecimalDemo() {
  return (
    <span className="text-4xl font-bold">
      <NumberTicker value={99.99} decimals={2} />
    </span>
  )
}
```

```tsx
import { NumberTicker } from "@glinui/ui"

export function NumberTickerCurrencyDemo() {
  return (
    <span className="text-4xl font-bold">
      <NumberTicker value={49999} formatOptions={{ style: "currency", currency: "USD", maximumFractionDigits: 0 }} />
    </span>
  )
}
```

```tsx
import { NumberTicker } from "@glinui/ui"

export function NumberTickerSlowDemo() {
  return (
    <span className="text-4xl font-bold">
      <NumberTicker value={500} duration={3} />
    </span>
  )
}
```

## Props

### NumberTickerProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `decimals?` | `number` | `0` |  |
| `delay?` | `number` | `0` | Delay in seconds. |
| `duration?` | `number` | `1.5` | Duration in seconds. |
| `engine?` | `EngineName` |  | Engine override: `css` (default), `motion`, `gsap` or a registered custom engine. |
| `formatOptions?` | `Intl.NumberFormatOptions` |  |  |
| `from?` | `number` | `0` |  |
| `motion?` | `MotionLevel` |  | Motion override. `none` renders the static final state, `subtle` is opacity only. |
| `value` | `number` |  |  |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Renders as a `` with `tabular-nums` for stable width during counting.
- Add `aria-label` to the parent if the number has semantic meaning beyond decoration.
- Reduced motion: When `prefers-reduced-motion` is active, the final value is displayed immediately without animation.

---

# Avatar

> Profile image with SVG-ready sources, fallback rendering, and multiple glass-aware surface variants.

- id: `avatar`
- type: primitive
- category: Data display
- tags: primitive
- docs: https://glinui.com/docs/components/radix/avatar
- markdown: https://glinui.com/md/avatar.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add avatar
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/avatar.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Avatar, AvatarGroup, SURFACE_VARIANTS, SURFACE_TONES, SURFACE_ELEVATIONS, SURFACE_VARIANT_ALIASES, STYLE_DEFAULT_VARIANT, GlinProvider } from "@glinui/ui"
```

## Usage

A team stack with presence dots and a +N overflow.

```tsx
import {
  Avatar,
  AvatarGroup,
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle
} from "@glinui/ui"

export function Demo() {
  return (
    <Card className="w-full max-w-md">
      <CardHeader>
        <CardTitle>Design system team</CardTitle>
        <CardDescription>8 members, 3 online now</CardDescription>
      </CardHeader>
      <CardContent className="flex flex-col gap-5">
        <AvatarGroup max={5}>
          <Avatar fallback="MK" tone="accent" status="online" />
          <Avatar fallback="JO" tone="success" status="online" />
          <Avatar fallback="PN" tone="info" status="away" />
          <Avatar fallback="DA" tone="warning" status="busy" />
          <Avatar fallback="HS" tone="danger" status="offline" />
          <Avatar fallback="LB" />
          <Avatar fallback="TR" />
          <Avatar fallback="EV" />
        </AvatarGroup>
        <div className="flex flex-wrap items-center gap-x-4 gap-y-2 text-xs text-[var(--color-muted)]">
          <span>Online</span>
          <span>Away</span>
          <span>Busy</span>
          <span>Offline</span>
        </div>
      </CardContent>
    </Card>
  )
}
```

### Variants

Every vocabulary variant on the default tone. Omit variant to follow the ambient design style.

```tsx
import { Avatar } from "@glinui/ui"

export function AvatarVariantsDemo() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <Avatar variant="glinr" fallback="GL" />
      <Avatar variant="solid" fallback="GL" />
      <Avatar variant="plain" fallback="GL" />
      <Avatar variant="soft" fallback="GL" />
      <Avatar variant="outline" fallback="GL" />
      <Avatar variant="ghost" fallback="GL" />
      <Avatar variant="gradient" fallback="GL" />
    </div>
  )
}
```

### Sizes and shapes

Six sizes, three radii, rings and presence.

```tsx
import { Avatar } from "@glinui/ui"

export function Demo() {
  return (
    <div className="flex w-full max-w-xl flex-col gap-6">
      <div className="flex flex-wrap items-end gap-4">
        {(["xs", "sm", "md", "lg", "xl", "2xl"] as const).map((size) => (
          <Avatar key={size} size={size} fallback="MK" tone="accent" />
        ))}
      </div>
      <div className="flex flex-wrap items-center gap-4">
        <Avatar size="lg" fallback="AB" radius="lg" tone="info" />
        <Avatar size="lg" fallback="CD" radius="md" tone="success" />
        <Avatar size="lg" fallback="EF" status="online" ring />
        <Avatar size="lg" fallback="GH" status="busy" variant="soft" tone="danger" />
      </div>
    </div>
  )
}
```

## Props

### AvatarGroupProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `max?` | `number` |  | Max avatars to show before +N overflow |
| `spacing?` | `"tight" \| "normal" \| "loose"` | `"normal"` | Overlap spacing |

### AvatarProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `alt?` | `string` | `""` |  |
| `fallback?` | `string` |  |  |
| `fallbackClassName?` | `string` |  |  |
| `imgClassName?` | `string` |  |  |
| `radius?` | `AvatarRadius` |  |  |
| `ring?` | `boolean` |  | Ring color for grouped avatars or emphasis |
| `size?` | `AvatarSize` |  |  |
| `src?` | `string` |  |  |
| `status?` | `AvatarStatus` |  | Online/offline status indicator |
| `tone?` | `SurfaceTone` |  | Colour tone for the vocabulary variants. |
| `variant?` | `SurfaceVariant \| ExtraVariant \| "default" \| "primary" \| "secondary" \| "destructive" \| "success" \| "w...` |  | Visual variant. Omit for the ambient design style (glinr: ringed, raised face). Vocabulary: glinr, solid, plain, soft, outline, ghost, gr... |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`, `primary`, `secondary`, `destructive`, `success`, `warning`, `info`, `raised`, `frosted`.

## Accessibility

- Image alt text provided via `alt` prop.
- Fallback text rendered when image fails to load.
- Status indicators include `aria-label` for screen readers.
- Provide a meaningful `alt` for identity-bearing avatars.
- Keep consistent avatar sizes in list/table contexts to reduce visual noise.
- Fallback initials ensure content remains identifiable when images fail.

ARIA:

- `role="img"` on image
- `aria-label` on status dot

- Reduced motion: Hover transitions respect `prefers-reduced-motion`. Transition effects on hover (scale, shadow) respect `prefers-reduced-motion` via the `motion-reduce:transition-none` utility.

---

# Item

> Flexible list row with media, content, actions, header, and footer slots.

- id: `item`
- type: primitive
- category: Data display
- tags: primitive
- docs: https://glinui.com/docs/components/radix/item
- markdown: https://glinui.com/md/item.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add item
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/item.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { ItemGroup, ItemSeparator, Item, ItemMedia, ItemContent, ItemTitle, ItemDescription, ItemActions } from "@glinui/ui"
```

## Usage

A settings list with an action button, switches and a navigation row.

```tsx
import { useState } from "react"
import { Bell, CaretRight, Gear, Moon, PencilSimple, UserCircle } from "@phosphor-icons/react"
import {
  Button,
  Item,
  ItemActions,
  ItemContent,
  ItemDescription,
  ItemGroup,
  ItemMedia,
  ItemSeparator,
  ItemTitle,
  Switch
} from "@glinui/ui"

export function Demo() {
  const [notify, setNotify] = useState(true)
  const [dark, setDark] = useState(false)
  return (
    <ItemGroup className="w-full max-w-lg">
      <Item>
        <ItemMedia variant="icon"><UserCircle aria-hidden /></ItemMedia>
        <ItemContent>
          <ItemTitle>Profile</ItemTitle>
          <ItemDescription>Name, avatar and public bio.</ItemDescription>
        </ItemContent>
        <ItemActions>
          <Button size="sm" variant="outline"><PencilSimple aria-hidden className="size-4" />Edit</Button>
        </ItemActions>
      </Item>
      <ItemSeparator />
      <Item>
        <ItemMedia variant="icon"><Bell aria-hidden /></ItemMedia>
        <ItemContent>
          <ItemTitle id="notify-label">Email notifications</ItemTitle>
          <ItemDescription>Weekly digest and mentions.</ItemDescription>
        </ItemContent>
        <ItemActions><Switch checked={notify} onCheckedChange={setNotify} aria-labelledby="notify-label" /></ItemActions>
      </Item>
      <ItemSeparator />
      <Item>
        <ItemMedia variant="icon"><Moon aria-hidden /></ItemMedia>
        <ItemContent>
          <ItemTitle id="dark-label">Dark appearance</ItemTitle>
          <ItemDescription>Follows your system by default.</ItemDescription>
        </ItemContent>
        <ItemActions><Switch checked={dark} onCheckedChange={setDark} aria-labelledby="dark-label" /></ItemActions>
      </Item>
      <ItemSeparator />
      <Item>
        <ItemMedia variant="icon"><Gear aria-hidden /></ItemMedia>
        <ItemContent>
          <ItemTitle>Advanced</ItemTitle>
          <ItemDescription>API tokens, webhooks and data export.</ItemDescription>
        </ItemContent>
        <ItemActions><CaretRight aria-hidden className="size-4 text-[var(--color-muted)]" /></ItemActions>
      </Item>
    </ItemGroup>
  )
}
```

### Variants

Every vocabulary variant on the default tone. Omit variant to follow the ambient design style.

```tsx
import { Item, ItemContent, ItemDescription, ItemTitle } from "@glinui/ui"

export function ItemVariantsDemo() {
  return (
    <div className="grid gap-3 md:grid-cols-2">
      <Item variant="glinr"><ItemContent><ItemTitle>glinr</ItemTitle><ItemDescription>Item description</ItemDescription></ItemContent></Item>
      <Item variant="solid"><ItemContent><ItemTitle>solid</ItemTitle><ItemDescription>Item description</ItemDescription></ItemContent></Item>
      <Item variant="plain"><ItemContent><ItemTitle>plain</ItemTitle><ItemDescription>Item description</ItemDescription></ItemContent></Item>
      <Item variant="soft"><ItemContent><ItemTitle>soft</ItemTitle><ItemDescription>Item description</ItemDescription></ItemContent></Item>
      <Item variant="outline"><ItemContent><ItemTitle>outline</ItemTitle><ItemDescription>Item description</ItemDescription></ItemContent></Item>
      <Item variant="ghost"><ItemContent><ItemTitle>ghost</ItemTitle><ItemDescription>Item description</ItemDescription></ItemContent></Item>
      <Item variant="gradient"><ItemContent><ItemTitle>gradient</ItemTitle><ItemDescription>Item description</ItemDescription></ItemContent></Item>
    </div>
  )
}
```

### Media list

Outline items with leading media, trailing actions and a soft warning item.

```tsx
import { CaretDown, Warning } from "@phosphor-icons/react"
import {
  Avatar,
  Button,
  Item,
  ItemActions,
  ItemContent,
  ItemDescription,
  ItemGroup,
  ItemMedia,
  ItemTitle
} from "@glinui/ui"

export function Demo() {
  const tracks = [
    { title: "Night Drive", artist: "Mira Lowe", length: "3:42", tone: "accent" as const },
    { title: "Paper Lanterns", artist: "The Quiet Hours", length: "4:08", tone: "success" as const },
    { title: "Low Tide", artist: "Oskar Venn", length: "2:56", tone: "info" as const }
  ]
  return (
    <ItemGroup className="w-full max-w-lg gap-2">
      {tracks.map((track) => (
        <Item key={track.title} variant="outline" size="sm">
          <ItemMedia>
            <Avatar radius="lg" fallback={track.title.slice(0, 2)} tone={track.tone} />
          </ItemMedia>
          <ItemContent>
            <ItemTitle>{track.title}</ItemTitle>
            <ItemDescription>{track.artist}</ItemDescription>
          </ItemContent>
          <ItemActions>
            <span className="text-xs tabular-nums text-[var(--color-muted)]">{track.length}</span>
            <Button variant="ghost" size="sm" aria-label={`More options for ${track.title}`}>
              <CaretDown aria-hidden className="size-4" />
            </Button>
          </ItemActions>
        </Item>
      ))}
      <Item variant="soft" tone="warning" size="sm">
        <ItemMedia variant="icon"><Warning aria-hidden /></ItemMedia>
        <ItemContent>
          <ItemTitle>Offline mode is on</ItemTitle>
          <ItemDescription>Only downloaded tracks will play.</ItemDescription>
        </ItemContent>
      </Item>
    </ItemGroup>
  )
}
```

## Props

### ItemMediaProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant?` | `"default" \| "icon" \| "image"` | `"default"` | Variant option from itemMediaVariants. |

### ItemProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `asChild?` | `boolean` | `false` | Render as the child element (e.g. a link) instead of a div. |
| `size?` | `"default" \| "sm"` |  |  |
| `tone?` | `SurfaceTone` |  |  |
| `variant?` | `SurfaceVariant \| "muted" \| "default" \| "raised" \| "frosted"` |  | Visual variant. Omit for the ambient design style (glinr: lift shell; plain: shadcn bordered row). Vocabulary: glinr, solid, plain, soft,... |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`, `icon`, `image`, `muted`, `raised`, `frosted`.

## Accessibility

- Items are neutral containers. Use `asChild` with an anchor or button for interactive rows.
- Interactive items show a violet focus ring.
- ItemSeparator exposes `role="separator"`.

Keyboard:

| Key | Action |
| --- | --- |
| Tab | Moves focus through interactive items and actions. |
| Enter | Activates a link item. |

- Reduced motion: Hover and border transitions are removed with reduced motion.

---

# Tree

> Hierarchical tree view for file structures, navigation, and nested data.

- id: `tree`
- type: primitive
- category: Data display
- tags: primitive
- docs: https://glinui.com/docs/components/radix/tree
- markdown: https://glinui.com/md/tree.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add tree
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/tree.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Tree, SURFACE_VARIANTS, SURFACE_TONES, SURFACE_ELEVATIONS, SURFACE_VARIANT_ALIASES, STYLE_DEFAULT_VARIANT, GlinProvider, GLIN_MOTIONS } from "@glinui/ui"
```

## Usage

A file explorer with file icons and change badges.

```tsx
import { FileCss, FileTsx } from "@phosphor-icons/react"
import { Tree } from "@glinui/ui"

export function Demo() {
  return (
    <div className="w-full max-w-sm">
      <Tree
        aria-label="Project files"
        nodes={[
          {
            label: "src",
            children: [
              {
                label: "components",
                children: [
                  { label: "button.tsx", href: "#", icon: <FileTsx className="size-3.5" />, badge: "M", badgeVariant: "warning" },
                  { label: "card.tsx", href: "#", icon: <FileTsx className="size-3.5" /> },
                  { label: "toast.tsx", href: "#", icon: <FileTsx className="size-3.5" />, badge: "new", badgeVariant: "success" }
                ]
              },
              {
                label: "styles",
                children: [{ label: "globals.css", href: "#", icon: <FileCss className="size-3.5" /> }]
              },
              { label: "index.ts", href: "#" }
            ]
          },
          { label: "package.json", href: "#" },
          { label: "tsconfig.json", href: "#", badge: "M", badgeVariant: "warning" }
        ]}
      />
    </div>
  )
}
```

### Variants

Every vocabulary variant on the default tone. Omit variant to follow the ambient design style.

```tsx
import { Tree } from "@glinui/ui"

export function TreeVariantsDemo() {
  return (
    <div className="grid gap-4 md:grid-cols-2">
      <Tree variant="glinr" nodes={[{ label: "src", children: [{ label: "index.ts" }] }, { label: "package.json" }]} />
      <Tree variant="solid" nodes={[{ label: "src", children: [{ label: "index.ts" }] }, { label: "package.json" }]} />
      <Tree variant="plain" nodes={[{ label: "src", children: [{ label: "index.ts" }] }, { label: "package.json" }]} />
      <Tree variant="soft" nodes={[{ label: "src", children: [{ label: "index.ts" }] }, { label: "package.json" }]} />
      <Tree variant="outline" nodes={[{ label: "src", children: [{ label: "index.ts" }] }, { label: "package.json" }]} />
      <Tree variant="ghost" nodes={[{ label: "src", children: [{ label: "index.ts" }] }, { label: "package.json" }]} />
      <Tree variant="gradient" nodes={[{ label: "src", children: [{ label: "index.ts" }] }, { label: "package.json" }]} />
    </div>
  )
}
```

### All Variants

Four surface variants match the design system, `default`, `glass`, `outline`, and `ghost`.

```tsx
import { Tree } from "@glinui/ui"

const nodes = [
  { label: "src", children: [{ label: "index.ts" }, { label: "App.tsx" }] },
  { label: "package.json" }
]

export function TreeVariantsDemo() {
  return (
    <div className="grid grid-cols-2 gap-4">
      <div>
        <p className="mb-2 text-xs font-semibold text-neutral-500 uppercase tracking-widest">Default</p>
        <Tree nodes={nodes} variant="default" />
      </div>
      <div>
        <p className="mb-2 text-xs font-semibold text-neutral-500 uppercase tracking-widest">Glass</p>
        <Tree nodes={nodes} variant="glass" />
      </div>
      <div>
        <p className="mb-2 text-xs font-semibold text-neutral-500 uppercase tracking-widest">Outline</p>
        <Tree nodes={nodes} variant="outline" />
      </div>
      <div>
        <p className="mb-2 text-xs font-semibold text-neutral-500 uppercase tracking-widest">Ghost</p>
        <Tree nodes={nodes} variant="ghost" />
      </div>
    </div>
  )
}
```

## Props

### TreeProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className?` | `string` |  | Extra classes for the tree root wrapper. |
| `defaultExpanded?` | `boolean` | `true` | Expand all folders by default |
| `nodes` | `TreeNode[]` |  | Tree data |
| `tone?` | `SurfaceTone` |  |  |
| `variant?` | `SurfaceVariant \| "default" \| "raised" \| "frosted"` |  | Visual variant. Omit for the ambient design style (glinr: lift shell; plain: flat bordered list). |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`, `raised`, `frosted`.

## Accessibility

- Folder nodes are interactive buttons with expand/collapse behavior.
- Linked leaf nodes render as anchor elements.
- Tree structure is conveyed visually through indentation and icons.
- The chevron icon provides a clear visual indicator of expanded/collapsed state.
- Leaf nodes that have an `href` render as `<a>` elements with proper `rel="noopener noreferrer"` when `external` is set.
- Nesting depth is communicated visually through `padding-left` indentation. For screen-reader depth cues, consider wrapping the component in a `<nav>` with an `aria-label`.

Keyboard:

| Key | Action |
| --- | --- |
| Enter / Space | Toggle folder expand/collapse. |
| Tab | Navigate between interactive nodes. |

- Reduced motion: Chevron rotation uses CSS transition that respects `prefers-reduced-motion`. The chevron rotation transition (`duration-150`) is a lightweight CSS transform. It respects `prefers-reduced-motion` via Tailwind's `motion-reduce:transition-none` utility if applied to `spotlightClassName`, and can be suppressed by adding `motion-reduce:transition-none` to the `className` prop.

---

# Image Comparison

> Before and after layers split by a draggable, keyboard operable slider handle.

- id: `image-comparison`
- type: primitive
- category: Data display
- tags: primitive, adapted
- docs: https://glinui.com/docs/components/radix/image-comparison
- markdown: https://glinui.com/md/image-comparison.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add image-comparison
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/image-comparison.json
```

Package:

```bash
npm install @glinui/ui @glinui/motion @glinui/tokens
```

## Import

```tsx
import { ImageComparison, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider, SURFACE_VARIANTS, SURFACE_TONES, SURFACE_ELEVATIONS, SURFACE_VARIANT_ALIASES } from "@glinui/ui"
```

## Usage

Adapted from Image Comparison by Motion Primitives (MIT). Modified: motion/react removed (the split is a CSS clip-path read from one custom property), pointer capture drag, a real slider role with keyboard support, ReactNode layers instead of image tags, vertical orientation, RTL and token surfaces.

The layers are any ReactNode, so you can compare images, screenshots, UI states or whole themes.

Two stylized UI mockups built from our components. Drag or use the arrow keys.

```tsx
import { ImageComparison } from "@glinui/ui"

export function Demo() {
  return <ImageComparison before={<OldUi />} after={<NewUi />} />
}
```

### Variants

Vertical split, and hover mode that follows a fine pointer.

```tsx
<ImageComparison orientation="vertical" before={a} after={b} />
<ImageComparison hover before={a} after={b} />
```

### States

Compare themes or any other pair of states.

```tsx
<ImageComparison beforeLabel="Light" afterLabel="Dark" before={light} after={dark} />
```

## Props

### ImageComparisonProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `after` | `React.ReactNode` |  | Layer shown behind, revealed past the handle. Any ReactNode. |
| `afterLabel?` | `string` | `"After"` |  |
| `before` | `React.ReactNode` |  | Layer shown from the start edge up to the handle. Any ReactNode. |
| `beforeLabel?` | `string` | `"Before"` |  |
| `defaultValue?` | `number` | `50` |  |
| `hover?` | `boolean` | `false` | Follow a fine pointer without pressing. Touch still drags. |
| `label?` | `string` | `"Comparison position"` | Accessible name of the slider handle. |
| `onValueChange?` | `(value: number) => void` |  |  |
| `orientation?` | `"horizontal" \| "vertical"` | `"horizontal"` |  |
| `showLabels?` | `boolean` | `true` | Show the visible Before and After chips. |
| `step?` | `number` | `2` | Arrow key step in percent. Shift or Page keys move 5 steps. |
| `value?` | `number` |  | Handle position, 0 to 100 (percent of the before layer shown). |
| `variant?` | `SurfaceVariant \| "default"` |  |  |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`.

## Accessibility

- The handle is role slider with aria-valuenow, aria-valuetext, aria-orientation and an accessible name.
- Everything a pointer can do works from the keyboard: arrows, Page keys, Home and End.
- touch-action is pan-y (pan-x when vertical) so a horizontal drag moves the handle while the page still scrolls the other way.
- Both layers are named groups, so their content stays readable.

Keyboard:

| Key | Action |
| --- | --- |
| ArrowLeft / ArrowRight | Move the handle (reversed in RTL). |
| ArrowUp / ArrowDown | Move the handle in vertical mode. |
| Shift + Arrow, PageUp / PageDown | Move five steps. |
| Home / End | Jump to 0 or 100. |

ARIA:

- `role="slider"` with `aria-valuemin`, `aria-valuemax`, `aria-valuenow`
- `aria-valuetext` reads both percentages
- `aria-orientation`

- Reduced motion: The short clip-path glide on keyboard moves only runs at motion level full. Dragging is always immediate.

## Provenance

Adapted from Motion Primitives (MIT, Copyright (c) 2024 ibelick). Upstream: https://motion-primitives.com/docs/image-comparison. Restyled to Glin tokens with accessibility and reduced motion review. Keep the attribution when you copy this component.

---

# Accordion

> Expandable content sections with smooth disclosure behavior.

- id: `accordion`
- type: primitive
- category: Layout and structure
- tags: primitive
- docs: https://glinui.com/docs/components/radix/accordion
- markdown: https://glinui.com/md/accordion.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add accordion
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/accordion.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Accordion, AccordionItem, AccordionTrigger, AccordionContent, SURFACE_VARIANTS, SURFACE_TONES, SURFACE_ELEVATIONS, SURFACE_VARIANT_ALIASES } from "@glinui/ui"
```

## Usage

A billing FAQ with the first answer open.

```tsx
import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from "@glinui/ui"

export function Demo() {
  const faqs = [
    ["Can I cancel at any time?", "Yes. Cancel from Billing and your plan stays active until the end of the period."],
    ["Do you offer discounts for nonprofits?", "Registered nonprofits get 50 percent off. Email billing with your registration number."],
    ["How do seats work?", "Each member who can edit counts as a seat. Viewers are always free."],
    ["Where is my data stored?", "In the region you choose at signup: US East, EU Central or Asia Pacific."]
  ]
  return (
    <section aria-labelledby="faq-title" className="flex w-full max-w-xl flex-col gap-4">
      <h3 id="faq-title" className="text-lg font-semibold">Billing questions</h3>
      <Accordion type="single" collapsible defaultValue="item-0">
        {faqs.map(([question, answer], index) => (
          <AccordionItem key={question} value={`item-${index}`}>
            <AccordionTrigger>{question}</AccordionTrigger>
            <AccordionContent>{answer}</AccordionContent>
          </AccordionItem>
        ))}
      </Accordion>
    </section>
  )
}
```

### Variants

glinr, plain (shadcn borders), solid, soft, outline and glass (opt-in).

```tsx
import { Accordion } from "@glinui/ui"

<Accordion variant="plain" type="single" collapsible>...</Accordion>
```

### Multiple open

Use type multiple with the separated look when readers compare answers.

```tsx
import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from "@glinui/ui"

export function Demo() {
  return (
    <Accordion type="multiple" defaultValue={["shipping", "returns"]} variant="separated" className="w-full max-w-xl">
      <AccordionItem value="shipping">
        <AccordionTrigger>Shipping</AccordionTrigger>
        <AccordionContent>Orders ship within 2 business days. Tracking is emailed once the parcel leaves our warehouse.</AccordionContent>
      </AccordionItem>
      <AccordionItem value="returns">
        <AccordionTrigger>Returns</AccordionTrigger>
        <AccordionContent>Return unused items within 30 days for a full refund to your original payment method.</AccordionContent>
      </AccordionItem>
      <AccordionItem value="warranty">
        <AccordionTrigger>Warranty</AccordionTrigger>
        <AccordionContent>Every product includes a two year warranty against manufacturing defects.</AccordionContent>
      </AccordionItem>
    </Accordion>
  )
}
```

## Props

### AccordionContentProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `contentSize?` | `Size` |  | Padding size matching the trigger |
| `size?` | `Size \| null` |  |  |
| `variant?` | `AccordionVariant \| null` |  |  |

### AccordionItemProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size?` | `Size \| null` |  |  |
| `variant?` | `AccordionVariant \| null` |  |  |

### AccordionProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant?` | `AccordionVariant` |  | Omitted follows the ambient style (glinr by default). `glass` is opt-in and needs a backdrop. |

### AccordionTriggerProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size?` | `Size \| null` |  |  |
| `variant?` | `AccordionVariant \| null` |  |  |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Built on Radix Accordion with full WAI-ARIA.
- Content regions are associated via `aria-controls`.
- Use concise trigger labels.

Keyboard:

| Key | Action |
| --- | --- |
| Enter / Space | Toggle the focused item open/closed. |
| Arrow Up | Move focus to the previous trigger. |
| Arrow Down | Move focus to the next trigger. |

ARIA:

- `role="region"` on content
- `aria-expanded` on trigger
- `aria-controls` linking trigger to content

- Reduced motion: Open/close height transitions respect `prefers-reduced-motion`.

---

# Collapsible

> Radix collapsible region with an animated trigger and content for show and hide sections.

- id: `collapsible`
- type: primitive
- category: Layout and structure
- tags: primitive
- docs: https://glinui.com/docs/components/radix/collapsible
- markdown: https://glinui.com/md/collapsible.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add collapsible
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/collapsible.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Collapsible, CollapsibleTrigger, CollapsibleContent, SURFACE_VARIANTS, SURFACE_TONES, SURFACE_ELEVATIONS, SURFACE_VARIANT_ALIASES, STYLE_DEFAULT_VARIANT } from "@glinui/ui"
```

## Usage

Expandable order details with a summary row that stays visible.

```tsx
import { useState } from "react"
import { CaretDown, Package, Truck } from "@phosphor-icons/react"
import {
  Button,
  Collapsible,
  CollapsibleContent,
  CollapsibleTrigger,
  IconFrame,
  Separator
} from "@glinui/ui"

export function Demo() {
  const [open, setOpen] = useState(true)
  return (
    <Collapsible open={open} onOpenChange={setOpen} className="w-full max-w-md">
      <div className="flex items-center justify-between gap-3 p-4">
        <div className="flex items-center gap-3">
          <IconFrame tone="accent" size="lg"><Package aria-hidden className="size-5" /></IconFrame>
          <div className="flex flex-col">
            <span className="text-sm font-semibold">Order #10482</span>
            <span className="text-xs text-[var(--color-muted)]">3 items, $148.00</span>
          </div>
        </div>
        <CollapsibleTrigger asChild>
          <Button variant="ghost" size="sm" aria-label={open ? "Hide order details" : "Show order details"}>
            <CaretDown aria-hidden className={open ? "size-4 rotate-180 transition-transform" : "size-4 transition-transform"} />
          </Button>
        </CollapsibleTrigger>
      </div>
      <CollapsibleContent>
        <Separator />
        <ul className="flex flex-col gap-3 p-4 text-sm">
          <li className="flex justify-between gap-3"><span>Canvas tote bag x2</span><span className="tabular-nums">$64.00</span></li>
          <li className="flex justify-between gap-3"><span>Ceramic mug</span><span className="tabular-nums">$24.00</span></li>
          <li className="flex justify-between gap-3"><span>Shipping</span><span className="tabular-nums">$12.00</span></li>
          <li className="flex items-center gap-2 text-[var(--color-muted)]"><Truck aria-hidden className="size-4" />Arrives Oct 12 to Oct 14</li>
        </ul>
      </CollapsibleContent>
    </Collapsible>
  )
}
```

### Variants

Every vocabulary variant on the default tone. Omit variant to follow the ambient design style.

```tsx
import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "@glinui/ui"

export function CollapsibleVariantsDemo() {
  return (
    <div className="grid gap-4 md:grid-cols-2">
      <Collapsible variant="glinr" defaultOpen className="p-4"><CollapsibleTrigger className="text-sm font-medium">glinr</CollapsibleTrigger><CollapsibleContent className="mt-2 text-sm">Content</CollapsibleContent></Collapsible>
      <Collapsible variant="solid" defaultOpen className="p-4"><CollapsibleTrigger className="text-sm font-medium">solid</CollapsibleTrigger><CollapsibleContent className="mt-2 text-sm">Content</CollapsibleContent></Collapsible>
      <Collapsible variant="plain" defaultOpen className="p-4"><CollapsibleTrigger className="text-sm font-medium">plain</CollapsibleTrigger><CollapsibleContent className="mt-2 text-sm">Content</CollapsibleContent></Collapsible>
      <Collapsible variant="soft" defaultOpen className="p-4"><CollapsibleTrigger className="text-sm font-medium">soft</CollapsibleTrigger><CollapsibleContent className="mt-2 text-sm">Content</CollapsibleContent></Collapsible>
      <Collapsible variant="outline" defaultOpen className="p-4"><CollapsibleTrigger className="text-sm font-medium">outline</CollapsibleTrigger><CollapsibleContent className="mt-2 text-sm">Content</CollapsibleContent></Collapsible>
      <Collapsible variant="ghost" defaultOpen className="p-4"><CollapsibleTrigger className="text-sm font-medium">ghost</CollapsibleTrigger><CollapsibleContent className="mt-2 text-sm">Content</CollapsibleContent></Collapsible>
      <Collapsible variant="gradient" defaultOpen className="p-4"><CollapsibleTrigger className="text-sm font-medium">gradient</CollapsibleTrigger><CollapsibleContent className="mt-2 text-sm">Content</CollapsibleContent></Collapsible>
    </div>
  )
}
```

### Show more

Reveal the rest of a list.

```tsx
import { useState } from "react"
import { Button, Collapsible, CollapsibleContent, CollapsibleTrigger } from "@glinui/ui"

export function Demo() {
  const [open, setOpen] = useState(false)
  const repos = ["glinui/ui", "glinui/docs", "glinui/tokens", "glinui/cli", "glinui/motion"]
  return (
    <Collapsible open={open} onOpenChange={setOpen} variant="plain" className="w-full max-w-sm">
      <div className="flex items-center justify-between gap-3 px-4 py-3">
        <h4 className="text-sm font-semibold">{repos.length} repositories starred</h4>
        <CollapsibleTrigger asChild>
          <Button variant="outline" size="sm">{open ? "Show less" : "Show all"}</Button>
        </CollapsibleTrigger>
      </div>
      <div className="mx-4 mb-3 rounded-lg border border-[var(--line-soft)] px-3 py-2 font-mono text-sm">{repos[0]}</div>
      <CollapsibleContent className="flex flex-col gap-2 px-4 pb-4">
        {repos.slice(1).map((repo) => (
          <div key={repo} className="rounded-lg border border-[var(--line-soft)] px-3 py-2 font-mono text-sm">{repo}</div>
        ))}
      </CollapsibleContent>
    </Collapsible>
  )
}
```

## Props

### CollapsibleProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tone?` | `SurfaceTone` |  |  |
| `variant?` | `SurfaceVariant \| "default" \| "raised" \| "frosted"` |  | Surface variant. Omit for the ambient design style (glinr by default, plain under `minimal`). Vocabulary: glinr, solid, plain, soft, outl... |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`, `raised`, `frosted`.

## Accessibility

- Trigger is a native button wired to the content with aria-controls.
- Hidden content is removed from the accessibility tree.
- Visible violet focus ring on the trigger.

Keyboard:

| Key | Action |
| --- | --- |
| Enter | Toggle the content. |
| Space | Toggle the content. |

ARIA:

- `aria-expanded` on the trigger
- `aria-controls` links trigger to content
- `data-state` open or closed

- Reduced motion: Content fades and slides 4px on open. With prefers-reduced-motion the animation is removed and content appears instantly.

---

# Scroll Area

> Custom-styled scroll container with vertical and horizontal scrollbars that keeps native scrolling.

- id: `scroll-area`
- type: primitive
- category: Layout and structure
- tags: primitive
- docs: https://glinui.com/docs/components/radix/scroll-area
- markdown: https://glinui.com/md/scroll-area.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add scroll-area
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/scroll-area.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { ScrollArea, ScrollBar, SURFACE_VARIANTS, SURFACE_TONES, SURFACE_ELEVATIONS, SURFACE_VARIANT_ALIASES, STYLE_DEFAULT_VARIANT, GLIN_MOTIONS } from "@glinui/ui"
```

## Usage

A long changelog in a fixed height region with a custom scrollbar.

```tsx
import {
  Badge,
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
  ScrollArea,
  Separator
} from "@glinui/ui"

export function Demo() {
  const releases = [
    { version: "2.8.0", date: "Oct 6", tag: "Feature", tone: "accent" as const, note: "Scheduled exports and a new CSV mapper." },
    { version: "2.7.3", date: "Sep 29", tag: "Fix", tone: "danger" as const, note: "Timezone drift in recurring reports." },
    { version: "2.7.2", date: "Sep 22", tag: "Fix", tone: "danger" as const, note: "Dropdown menus now close on route change." },
    { version: "2.7.0", date: "Sep 15", tag: "Feature", tone: "accent" as const, note: "Dark appearance for the billing portal." },
    { version: "2.6.4", date: "Sep 8", tag: "Perf", tone: "success" as const, note: "Dashboard loads 38 percent faster." },
    { version: "2.6.0", date: "Aug 30", tag: "Feature", tone: "accent" as const, note: "Team roles with per-project access." },
    { version: "2.5.2", date: "Aug 21", tag: "Fix", tone: "danger" as const, note: "Webhook retries respect the backoff header." },
    { version: "2.5.0", date: "Aug 12", tag: "Feature", tone: "accent" as const, note: "Audit log with 90 day retention." }
  ]
  return (
    <Card className="w-full max-w-md">
      <CardHeader>
        <CardTitle>Changelog</CardTitle>
        <CardDescription>Recent releases</CardDescription>
      </CardHeader>
      <CardContent>
        <ScrollArea variant="outline" className="h-72" aria-label="Release history">
          <ol className="flex flex-col">
            {releases.map((release, index) => (
              <li key={release.version}>
                {index > 0 ? <Separator /> : null}
                <div className="flex flex-col gap-1.5 p-4">
                  <div className="flex items-center justify-between gap-3">
                    <span className="font-mono text-sm font-semibold">v{release.version}</span>
                    <span className="text-xs text-[var(--color-muted)]">{release.date}</span>
                  </div>
                  <p className="text-sm">{release.note}</p>
                  <Badge variant="soft" tone={release.tone} size="sm" className="w-fit">{release.tag}</Badge>
                </div>
              </li>
            ))}
          </ol>
        </ScrollArea>
      </CardContent>
    </Card>
  )
}
```

### Variants

Every vocabulary variant on the default tone. Omit variant to follow the ambient design style. Omitted variant renders a chromeless region like the shadcn primitive.

```tsx
import { ScrollArea } from "@glinui/ui"

export function ScrollAreaVariantsDemo() {
  return (
    <div className="grid gap-4 md:grid-cols-2">
      <ScrollArea variant="glinr" className="h-24 w-full"><div className="space-y-1 p-3 text-sm"><div>First row</div><div>Second row</div><div>Third row</div><div>Fourth row</div></div></ScrollArea>
      <ScrollArea variant="solid" className="h-24 w-full"><div className="space-y-1 p-3 text-sm"><div>First row</div><div>Second row</div><div>Third row</div><div>Fourth row</div></div></ScrollArea>
      <ScrollArea variant="soft" className="h-24 w-full"><div className="space-y-1 p-3 text-sm"><div>First row</div><div>Second row</div><div>Third row</div><div>Fourth row</div></div></ScrollArea>
      <ScrollArea variant="outline" className="h-24 w-full"><div className="space-y-1 p-3 text-sm"><div>First row</div><div>Second row</div><div>Third row</div><div>Fourth row</div></div></ScrollArea>
      <ScrollArea variant="ghost" className="h-24 w-full"><div className="space-y-1 p-3 text-sm"><div>First row</div><div>Second row</div><div>Third row</div><div>Fourth row</div></div></ScrollArea>
      <ScrollArea variant="gradient" className="h-24 w-full"><div className="space-y-1 p-3 text-sm"><div>First row</div><div>Second row</div><div>Third row</div><div>Fourth row</div></div></ScrollArea>
    </div>
  )
}
```

### Horizontal

A horizontal strip with its own scrollbar.

```tsx
import { ScrollArea, ScrollBar } from "@glinui/ui"

export function Demo() {
  const shots = ["Overview", "Reports", "Billing", "Members", "Audit log", "Webhooks", "API keys", "Settings"]
  return (
    <ScrollArea className="w-full max-w-lg whitespace-nowrap rounded-xl border border-[var(--line-soft)]" aria-label="Screens">
      <div className="flex gap-3 p-4">
        {shots.map((shot, index) => (
          <figure key={shot} className="flex shrink-0 flex-col gap-2">
            <div className="flex h-24 w-40 items-center justify-center rounded-lg bg-[var(--surface-3)] text-xs font-medium text-[var(--color-muted)]">
              {index + 1} / {shots.length}
            </div>
            <figcaption className="text-sm font-medium">{shot}</figcaption>
          </figure>
        ))}
      </div>
      <ScrollBar orientation="horizontal" />
    </ScrollArea>
  )
}
```

## Props

### ScrollAreaProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tone?` | `SurfaceTone` |  |  |
| `variant?` | `SurfaceVariant \| "default"` |  | Surface variant. Omit (or `plain`) for a chromeless scroll region like the shadcn primitive. Vocabulary: glinr, solid, soft, outline, gho... |
| `viewportClassName?` | `string` |  | Class names for the scrollable viewport. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`.

## Accessibility

- Native scrolling is preserved, so wheel, touch, and keyboard scroll work as usual.
- The viewport is focusable with a visible violet focus ring so keyboard users can scroll it.

Keyboard:

| Key | Action |
| --- | --- |
| Tab | Focus the viewport. |
| Arrow keys / PageUp / PageDown | Scroll the focused viewport. |

ARIA:

- Add `aria-label` or `aria-labelledby` on the viewport region when it is a landmark.

- Reduced motion: Scrollbar fade transitions are disabled with reduced motion.

---

# Separator

> Visual divider for grouping content with orientation support.

- id: `separator`
- type: primitive
- category: Layout and structure
- tags: primitive
- docs: https://glinui.com/docs/components/radix/separator
- markdown: https://glinui.com/md/separator.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add separator
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/separator.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Separator, GlinProvider, GLIN_MOTIONS, GLIN_ENGINES, GLIN_SURFACES, GLIN_STYLES, GLIN_ACCENTS, GLIN_BASES } from "@glinui/ui"
```

## Usage

Vertical dividers in a tab row, labeled and icon dividers, and a receipt total.

```tsx
import { Sparkle } from "@phosphor-icons/react"
import { Separator } from "@glinui/ui"

export function Demo() {
  return (
    <div className="flex w-full max-w-md flex-col gap-5">
      <div className="flex h-5 items-center gap-4 text-sm">
        <span>Overview</span>
        <Separator orientation="vertical" />
        <span>Activity</span>
        <Separator orientation="vertical" />
        <span>Settings</span>
      </div>
      <Separator label="or continue with" />
      <Separator icon={<Sparkle aria-hidden className="size-4" />} variant="gradient" />
      <div className="flex flex-col gap-3 text-sm">
        <div className="flex justify-between"><span>Subtotal</span><span className="tabular-nums">$148.00</span></div>
        <div className="flex justify-between"><span>Shipping</span><span className="tabular-nums">$12.00</span></div>
        <Separator variant="dashed" />
        <div className="flex justify-between font-semibold"><span>Total</span><span className="tabular-nums">$160.00</span></div>
      </div>
    </div>
  )
}
```

### Variants

Omitted `variant` follows the ambient style: an engraved glinr hairline, a flat plain line, or glass.

```tsx
import { Separator } from "@glinui/ui"

<Separator />
<Separator variant="plain" />
<Separator variant="hairline" />
<Separator variant="dashed" />
```

### Variants

```tsx
import { Separator } from "@glinui/ui"

export function SeparatorVariantDemo() {
  return (
    <div className="space-y-4">
      <Separator variant="default" />
      <Separator variant="glass" />
      <Separator variant="outline" />
      <Separator variant="ghost" />
    </div>
  )
}
```

## Props

### SeparatorProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `decorative?` | `boolean` | `true` | When true the element is purely visual (default). When false, role="separator" is applied. |
| `icon?` | `React.ReactNode` |  | Icon node rendered centred on the separator line. Overrides label when both are provided. |
| `label?` | `string` |  | Text label rendered centred on the separator line. |
| `orientation?` | `"horizontal" \| "vertical"` | `"horizontal"` | Variant option from lineVariants. |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Variant option from lineVariants. |
| `variant?` | `VariantProps<typeof lineVariants>["variant"]` |  | Line style. Omitted (or `default`) follows the ambient design style: glinr (engraved hairline), plain (flat 1px border color) or glass. O... |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `variant`.

## Accessibility

- Uses `role="separator"` when not decorative.
- Set `decorative={false}` for semantic separators.
- Use `decorative={false}` for separators that convey structural meaning.
- Use `orientation="vertical"` for column-like content splits.

ARIA:

- `role="separator"` when not decorative
- `aria-orientation`
- `aria-hidden` when decorative

- Reduced motion: No animation dependencies. Separator is a static element and does not use motion.

---

# Aspect Ratio

> Constrains content to a width to height ratio with optional surface frame.

- id: `aspect-ratio`
- type: primitive
- category: Layout and structure
- tags: primitive
- docs: https://glinui.com/docs/components/radix/aspect-ratio
- markdown: https://glinui.com/md/aspect-ratio.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add aspect-ratio
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/aspect-ratio.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { AspectRatio, SURFACE_VARIANTS, SURFACE_TONES, SURFACE_ELEVATIONS, SURFACE_VARIANT_ALIASES, STYLE_DEFAULT_VARIANT, GLIN_MOTIONS, GLIN_ENGINES } from "@glinui/ui"
```

## Usage

Four common ratios.

```tsx
import { AspectRatio, Badge } from "@glinui/ui"

export function Demo() {
  return (
    <div className="grid w-full max-w-2xl gap-4 sm:grid-cols-2">
      {[
        { ratio: 16 / 9, label: "16:9", tone: "from-[var(--color-accent)]" },
        { ratio: 4 / 3, label: "4:3", tone: "from-[var(--tone-info)]" },
        { ratio: 1, label: "1:1", tone: "from-[var(--tone-success)]" },
        { ratio: 9 / 16, label: "9:16", tone: "from-[var(--tone-warning)]" }
      ].map((item) => (
        <div key={item.label} className={item.ratio < 1 ? "mx-auto w-1/2 sm:w-2/3" : ""}>
          <AspectRatio ratio={item.ratio} className="rounded-xl">
            <div className={`flex size-full items-end bg-gradient-to-br ${item.tone} to-[var(--surface-3)] p-3`}>
              <Badge variant="glass">{item.label}</Badge>
            </div>
          </AspectRatio>
        </div>
      ))}
    </div>
  )
}
```

### Variants

Every vocabulary variant on the default tone. Omit variant to follow the ambient design style.

```tsx
import { AspectRatio } from "@glinui/ui"

export function AspectRatioVariantsDemo() {
  return (
    <div className="grid gap-4 md:grid-cols-3">
      <AspectRatio variant="glinr" ratio={16 / 9}><div className="grid size-full place-items-center text-sm">glinr</div></AspectRatio>
      <AspectRatio variant="solid" ratio={16 / 9}><div className="grid size-full place-items-center text-sm">solid</div></AspectRatio>
      <AspectRatio variant="soft" ratio={16 / 9}><div className="grid size-full place-items-center text-sm">soft</div></AspectRatio>
      <AspectRatio variant="outline" ratio={16 / 9}><div className="grid size-full place-items-center text-sm">outline</div></AspectRatio>
      <AspectRatio variant="ghost" ratio={16 / 9}><div className="grid size-full place-items-center text-sm">ghost</div></AspectRatio>
      <AspectRatio variant="gradient" ratio={16 / 9}><div className="grid size-full place-items-center text-sm">gradient</div></AspectRatio>
    </div>
  )
}
```

### In a card

A 16:9 cover on top of a card.

```tsx
import { Sparkle } from "@phosphor-icons/react"
import { AspectRatio, Badge, Card } from "@glinui/ui"

export function Demo() {
  return (
    <Card className="w-full max-w-sm overflow-hidden p-0">
      <AspectRatio ratio={16 / 9}>
        <div className="flex size-full items-center justify-center bg-gradient-to-br from-[var(--color-accent)] to-[var(--surface-3)]">
          <Sparkle aria-hidden weight="fill" className="size-10 text-white" />
        </div>
      </AspectRatio>
      <div className="flex flex-col gap-2 p-4">
        <Badge variant="soft" tone="accent" size="sm" className="w-fit">Guide</Badge>
        <h3 className="text-base font-semibold">Designing empty states</h3>
        <p className="text-sm text-[var(--color-muted)]">Six patterns that turn a blank screen into the next step.</p>
      </div>
    </Card>
  )
}
```

## Props

### AspectRatioProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tone?` | `SurfaceTone` |  |  |
| `variant?` | `SurfaceVariant \| "default"` |  | Surface variant. Omit (or `plain`) for a chromeless frame like the shadcn primitive. Vocabulary: glinr, solid, soft, outline, ghost, grad... |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`.

## Accessibility

- Layout-only primitive with no implicit role.
- Provide `alt` on images or `aria-label` on media placed inside.

ARIA:

- No ARIA attributes are added.

- Reduced motion: No motion is used.

---

# Browser Frame

> Generic browser window chrome drawn in CSS with a slot for any content.

- id: `browser-frame`
- type: primitive
- category: Layout and structure
- tags: primitive, adapted
- docs: https://glinui.com/docs/components/radix/browser-frame
- markdown: https://glinui.com/md/browser-frame.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add browser-frame
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/browser-frame.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { BrowserFrame, SURFACE_VARIANTS, SURFACE_TONES, SURFACE_ELEVATIONS, SURFACE_VARIANT_ALIASES, STYLE_DEFAULT_VARIANT, GlinProvider, GLIN_MOTIONS } from "@glinui/ui"
```

## Usage

Adapted from Safari by Magic UI (MIT), renamed to avoid the Apple trademark.

Improvements: generic CSS chrome drawn with tokens instead of one SVG, a children slot for real UI (the original only took image or video), real address text, glass, simple mode and no bundled media.

A billing screen inside a browser window.

```tsx
import { CreditCard } from "@phosphor-icons/react"
import { Avatar, BrowserFrame, Button, Separator } from "@glinui/ui"

export function Demo() {
  return (
    <BrowserFrame url="app.northwind.io/billing" className="w-full max-w-2xl">
      <div className="flex flex-col gap-4 p-5">
        <div className="flex items-center justify-between gap-3">
          <div className="flex items-center gap-3">
            <Avatar fallback="NS" tone="accent" />
            <div className="flex flex-col">
              <span className="text-sm font-semibold">Northwind Studio</span>
              <span className="text-xs text-[var(--color-muted)]">Team plan</span>
            </div>
          </div>
          <Button size="sm" variant="outline"><CreditCard aria-hidden className="size-4" />Manage billing</Button>
        </div>
        <Separator />
        <div className="grid gap-3 sm:grid-cols-3">
          {[["Spend", "$1,240"], ["Seats", "12"], ["Invoices", "8"]].map(([label, value]) => (
            <div key={label} className="rounded-lg bg-[var(--surface-2)] p-3">
              <p className="text-xs text-[var(--color-muted)]">{label}</p>
              <p className="text-lg font-semibold tabular-nums">{value}</p>
            </div>
          ))}
        </div>
      </div>
    </BrowserFrame>
  )
}
```

### Modes

A titled window and an address bar window.

```tsx
import { Bell, Stack } from "@phosphor-icons/react"
import { BrowserFrame, IconFrame } from "@glinui/ui"

export function Demo() {
  return (
    <div className="grid w-full max-w-3xl gap-4 md:grid-cols-2">
      <BrowserFrame mode="simple" title="Release notes">
        <div className="flex items-center gap-3 p-5 text-sm">
          <IconFrame tone="success"><Stack aria-hidden className="size-4" /></IconFrame>
          Version 2.8 is live for all workspaces.
        </div>
      </BrowserFrame>
      <BrowserFrame url="glinui.com/docs">
        <div className="flex items-center gap-3 p-5 text-sm">
          <IconFrame tone="accent"><Bell aria-hidden className="size-4" /></IconFrame>
          Subscribe to product updates.
        </div>
      </BrowserFrame>
    </div>
  )
}
```

## Props

### BrowserFrameProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `frameLabel?` | `string` |  | Accessible name for the frame region. |
| `mode?` | `"default" \| "simple"` | `"default"` | `default` shows an address bar, `simple` a centered window title only. |
| `title?` | `string` |  | Window title for `simple` mode. |
| `tone?` | `SurfaceTone` |  |  |
| `url?` | `string` | `"glinui.com"` | Text in the address bar. |
| `variant?` | `SurfaceVariant \| "default" \| "raised" \| "frosted"` |  | Visual variant. Omit for the ambient design style (glinr: lift shell with a raised chrome strip; plain: flat bordered window). |
| `viewportClassName?` | `string` |  | Extra classes for the viewport (content) area. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`, `raised`, `frosted`.

## Accessibility

- The traffic-light dots are decorative and aria-hidden.
- The address is a real text element, and children keep their own semantics and focus order.
- The frame is a labelled group and does not use role=img, so inner content stays reachable.

ARIA:

- `role=group` with `aria-label`
- Dots use `aria-hidden`
- `alt` is required when `src` is used

- Reduced motion: Static chrome with no animation.

## Provenance

Adapted from Magic UI (MIT, Copyright (c) Magic UI). Upstream: https://magicui.design/docs/components/safari. Restyled to Glin tokens with accessibility and reduced motion review. Keep the attribution when you copy this component.

---

# Progressive Blur

> Edge overlay that blurs content progressively using stacked masked backdrop filters.

- id: `progressive-blur`
- type: primitive
- category: Layout and structure
- tags: primitive, adapted
- docs: https://glinui.com/docs/components/radix/progressive-blur
- markdown: https://glinui.com/md/progressive-blur.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add progressive-blur
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/progressive-blur.json
```

Package:

```bash
npm install @glinui/ui @glinui/motion @glinui/tokens
```

## Import

```tsx
import { ProgressiveBlur, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider } from "@glinui/ui"
```

## Usage

Adapted from Progressive Blur by Motion Primitives (MIT). Modified: motion/react removed, `start` and `end` directions follow text direction, per-layer mask and blur come from CSS variables instead of inline styles, layers are capped at 8, and motion none swaps the stack for a single gradient fade.

Place it inside a `relative` scroll container, or above a sticky header, and size it with `size`. Add `isolate` to a rounded `overflow-hidden` parent so the blur is clipped to its corners. It never receives pointer events.

Each layer is a `backdrop-filter`, which is expensive over large areas. Keep overlays small (under about 160px thick) and use fewer layers on low-end devices.

The bottom of a scrolling feed dissolves into blur.

```tsx
import { ProgressiveBlur } from "@glinui/ui"

<div className="relative h-56 overflow-hidden">
  <List />
  <ProgressiveBlur direction="bottom" size={72} />
</div>
```

### Variants

All four edges.

```tsx
<ProgressiveBlur direction="start" size={56} />
```

### States

Fewer, stronger layers or many soft ones.

```tsx
<ProgressiveBlur blurLayers={3} blurIntensity={2} />
<ProgressiveBlur blurLayers={8} blurIntensity={0.6} size={96} />
```

## Props

### ProgressiveBlurProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `blurIntensity?` | `number` | `1` | Extra blur in pixels added per layer (the strongest layer blurs by `(layers - 1) * blurIntensity`). |
| `blurLayers?` | `number` | `MAX_LAYERS` | Number of stacked backdrop-filter layers, clamped to 2..8. |
| `direction?` | `"top" \| "bottom" \| "start" \| "end"` | `"bottom"` | Variant option from progressiveBlurVariants. |
| `size?` | `number \| string` |  | Thickness of the overlay along its axis. A number is pixels, a string is any CSS length. |
| `variant?` | `"default" \| "plain" \| "glass"` | `"default"` | Variant option from progressiveBlurVariants. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`, `plain`, `glass`.

## Accessibility

- Decorative: aria-hidden and pointer-events-none, so links and scrolling underneath keep working.
- Do not rely on it to hide content from users; the text underneath stays readable by assistive tech.
- Hidden under forced-colors.

ARIA:

- `aria-hidden="true"`
- `data-mode` is `blur` or `fade`

- Reduced motion: The blur itself is static. At motion level none the overlay becomes a single gradient fade with no backdrop-filter, which also helps low-power devices.

## Provenance

Adapted from Motion Primitives (MIT, Copyright (c) 2024 ibelick). Upstream: https://motion-primitives.com/docs/progressive-blur. Restyled to Glin tokens with accessibility and reduced motion review. Keep the attribution when you copy this component.

---

# Cylinder Carousel

> Slides on a rotating 3D ring with buttons, arrow keys, swipe and a pausable autoplay.

- id: `cylinder-carousel`
- type: primitive
- category: Layout and structure
- tags: primitive, adapted
- docs: https://glinui.com/docs/components/radix/cylinder-carousel
- markdown: https://glinui.com/md/cylinder-carousel.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add cylinder-carousel
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/cylinder-carousel.json
```

Package:

```bash
npm install @glinui/ui @glinui/motion @glinui/tokens
```

## Import

```tsx
import { CylinderCarousel, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider, SURFACE_VARIANTS, SURFACE_TONES, SURFACE_ELEVATIONS, SURFACE_VARIANT_ALIASES } from "@glinui/ui"
```

## Usage

Adapted from Cylinder Carousel by Vengeance UI (MIT). Modified: ReactNode slides instead of image urls, step based rotation (buttons, arrow keys, swipe, autoplay) instead of an endless CSS spin, carousel aria semantics, inert rear slides, token surfaces, RTL and a flat scroll-snap fallback at motion none.

Geometry is computed in JS (the ring radius from card width, gap and count), so it does not rely on the CSS tan() function.

Autoplay is off by default. When on, it pauses on hover and focus, a visible pause button is shown (WCAG 2.2.2) and it never runs under reduced motion.

Six gradient slides on a ring. Use the buttons, arrow keys or swipe.

```tsx
import { CylinderCarousel } from "@glinui/ui"

export function Demo() {
  return (
    <CylinderCarousel
      label="Featured palettes"
      items={palettes.map((p) => <PaletteTile key={p.id} palette={p} />)}
    />
  )
}
```

### Variants

glinr is the default surface, plain is flat, solid is a neutral tonal face.

```tsx
<CylinderCarousel variant="plain" items={items} cardWidth={140} cardHeight={180} />
```

### States

Autoplay pauses on hover and focus, and has a pause button.

```tsx
<CylinderCarousel autoPlay autoPlayInterval={2800} items={items} />
```

## Props

### CylinderCarouselProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `autoPlay?` | `boolean` | `false` | Rotate on a timer. Needs motion level full. Pauses on hover and focus, with a visible pause button. |
| `autoPlayInterval?` | `number` | `3500` | Milliseconds between automatic steps. |
| `cardHeight?` | `number` | `280` | Slide height in pixels. |
| `cardWidth?` | `number` | `200` | Slide width in pixels. |
| `defaultValue?` | `number` | `0` | Uncontrolled initial front slide index. |
| `gap?` | `number` | `24` | Gap between neighbouring slides on the ring, in pixels. |
| `getSlideLabel?` | `(index: number, total: number) => string` |  | Name for the slide, receives the 0 based index. Defaults to "n of N". |
| `items` | `React.ReactNode[]` |  | Slide content. Any ReactNode, no image urls required. |
| `label?` | `string` | `"Carousel"` | Accessible name of the carousel region. |
| `onValueChange?` | `(index: number) => void` |  |  |
| `showControls?` | `boolean` | `true` | Show previous and next buttons. |
| `value?` | `number` |  | Controlled front slide index. |
| `variant?` | `SurfaceVariant \| "default"` |  | Surface of each slide frame. Omit to follow the ambient style. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`.

## Accessibility

- The root is a region with aria-roledescription carousel. Each slide is a group with aria-roledescription slide and a name such as 3 of 6.
- Only the front slide is interactive. Rear slides are inert so focus and screen readers never land on content that is turned away.
- The viewport is focusable and takes arrow keys. Previous and next are real buttons. Swipe works on touch.
- aria-live is off while autoplay is running and polite otherwise. Autoplay pauses on hover and focus and has a pause button.

Keyboard:

| Key | Action |
| --- | --- |
| ArrowRight / ArrowLeft | Next or previous slide (reversed in RTL). |
| Home / End | First or last slide. |
| Tab | Moves to the controls and into the front slide. |

ARIA:

- `role="region"` with `aria-roledescription="carousel"`
- `aria-roledescription="slide"` and `aria-label="n of N"` on slides
- `inert` on non-front slides
- `aria-live` off during autoplay

- Reduced motion: Autoplay only runs at motion level full, so reduced motion turns it off. Rotation transitions are dropped at subtle. Motion level none renders a flat scroll-snap list with every slide reachable.

## Provenance

Adapted from Vengeance UI (MIT, Copyright (c) 2025-2026 Ashutoshx7). Upstream: https://github.com/Ashutoshx7/VengeanceUI/blob/0376d8e37b4a565016cce1064d7b96905c4494ab/src/components/ui/cylinder-carousel.tsx. Restyled to Glin tokens with accessibility and reduced motion review. Keep the attribution when you copy this component.

---

# Circular Gallery

> Tiles on a ring that rotates to the front with drag inertia, keys, click and optional autorotate.

- id: `circular-gallery`
- type: primitive
- category: Layout and structure
- tags: primitive
- docs: https://glinui.com/docs/components/radix/circular-gallery
- markdown: https://glinui.com/md/circular-gallery.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add circular-gallery
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/circular-gallery.json
```

Package:

```bash
npm install @glinui/ui @glinui/motion @glinui/tokens
```

## Import

```tsx
import { CircularGallery, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider, SURFACE_VARIANTS, SURFACE_TONES, SURFACE_ELEVATIONS, SURFACE_VARIANT_ALIASES } from "@glinui/ui"
```

## Usage

Our own design (clean-room, no upstream code). Tiles sit on a ring seen from the front: the front tile is large and sharp, the others shrink, dim and blur toward the back.

Drag has inertia and eases to the nearest tile. Positions are computed in JS and written as CSS variables from a rAF loop, so a drag causes no React renders.

Compared with CylinderCarousel: the gallery is a continuous, draggable ring with a front caption and click to focus. The carousel is a step based slide show.

Six gradient tiles on a ring. Drag, click a back tile or use the arrow keys.

```tsx
import { CircularGallery } from "@glinui/ui"

export function Demo() {
  return <CircularGallery label="Collections" items={items} />
}
```

### Variants

glinr, plain and solid tile surfaces.

```tsx
<CircularGallery variant="plain" items={items} tileWidth={110} tileHeight={140} />
```

### States

Auto rotate, paused by hover and focus.

```tsx
<CircularGallery autoRotate autoRotateInterval={2600} items={items} />
```

## Props

### CircularGalleryProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `autoRotate?` | `boolean` | `false` | Rotate on a timer. Needs motion level full. Pauses on hover, focus and drag. |
| `autoRotateInterval?` | `number` | `3200` | Milliseconds between automatic steps. |
| `defaultValue?` | `number` | `0` |  |
| `items` | `CircularGalleryItem[]` |  |  |
| `label?` | `string` | `"Gallery"` | Accessible name of the gallery. |
| `onValueChange?` | `(index: number) => void` |  |  |
| `radius?` | `number` |  | Ring radius in pixels. Defaults to a size that fits the tiles. |
| `showCaption?` | `boolean` | `true` | Show the caption of the front tile under the ring. |
| `tileHeight?` | `number` | `190` |  |
| `tileWidth?` | `number` | `150` |  |
| `tilt?` | `number` | `8` | Camera tilt in degrees. Positive looks down on the ring. |
| `value?` | `number` |  | Controlled front item index. |
| `variant?` | `SurfaceVariant \| "default"` |  |  |
| `wheel?` | `boolean` | `false` | Let the wheel or trackpad rotate the ring. Off by default so page scroll is never captured. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`.

## Accessibility

- A listbox with option tiles, a roving tabindex and aria-current on the front tile. Back tiles are still focusable and clicking or focusing one brings it forward.
- Arrow keys, Home and End move the front tile and focus together.
- Drag and wheel are conveniences only, every action has a key and click equivalent.
- Auto rotate pauses on hover, focus and drag and is off under reduced motion.

Keyboard:

| Key | Action |
| --- | --- |
| ArrowRight / ArrowLeft | Next or previous tile (reversed in RTL). |
| Home / End | First or last tile. |
| Enter / click | Bring a tile to the front. |

ARIA:

- `role="listbox"` and `role="option"` tiles
- `aria-current` and `aria-selected` on the front tile
- `aria-posinset` and `aria-setsize`

- Reduced motion: Easing and auto rotate only run at motion level full. Otherwise the ring snaps to the chosen tile instantly.

---

# Hero Section

> Landing hero with announcement pill, actions, media slot and logo strip in centered, split and stacked layouts.

- id: `hero-section`
- type: primitive
- category: Blocks
- tags: primitive
- docs: https://glinui.com/docs/components/radix/hero-section
- markdown: https://glinui.com/md/hero-section.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add hero-section
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/hero-section.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { HeroSection, GlinProvider, SURFACE_VARIANTS, SURFACE_TONES, SURFACE_ELEVATIONS, SURFACE_VARIANT_ALIASES, STYLE_DEFAULT_VARIANT, GLIN_MOTIONS } from "@glinui/ui"
```

## Usage

Own design, composed from Badge, Heading, Text, Button and Reveal. Layout inspiration only from public MIT hero blocks; no upstream markup is copied.

The `background` slot takes any decorative node (GridPattern, AuroraBackground, a gradient). It is aria-hidden and never intercepts pointer events.

Links render real anchors through `href`; pass `onClick` for client routers.

Split hero with an announcement pill, two actions, a media slot, a grid background and a logo strip.

```tsx
import { HeroSection, LogoCloud } from "@glinui/ui"

<HeroSection
  layout="split"
  announcement="Release 0.2 is out"
  title="Interfaces that feel finished on day one"
  description="Tokens, primitives and blocks that share one lighting model."
  primaryAction={{ label: "Get started", href: "/start" }}
  secondaryAction={{ label: "Read the docs", href: "/docs" }}
  media={<Screenshot />}
  background={<GridPattern />}
  logos={<LogoCloud items={logos} />}
/>
```

### Variants

Centered with a pill, and stacked media on a glass shell.

```tsx
<HeroSection title="Centered with a pill" announcement="New" primaryAction={{ label: "Start", href: "#" }} />
<HeroSection variant="glass" layout="stacked-media" title="Stacked media" media={<Screenshot />} />
```

### In a layout

A hero followed by a feature section.

```tsx
<>
  <HeroSection ... />
  <FeatureGrid ... />
</>
```

## Props

### HeroSectionProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `announcement?` | `React.ReactNode` |  | Small pill above the headline. A string gets a dot, a node is rendered as given. |
| `announcementHref?` | `string` |  | Link target for the announcement pill. |
| `background?` | `React.ReactNode` |  | Decorative layer behind the content (AuroraBackground, GridPattern, a gradient). Hidden from assistive tech. |
| `description?` | `React.ReactNode` |  | Lede paragraph under the headline. |
| `entrance?` | `boolean` | `true` | Entrance reveal of the copy. Follows the motion level; none at level none. Default true. |
| `headingLevel?` | `1 \| 2` | `1` | Heading level of the headline. Default 1. |
| `layout?` | `"centered" \| "split" \| "stacked-media"` | `"centered"` | Variant option from contentVariants. |
| `logos?` | `React.ReactNode` |  | Optional strip under the actions (a LogoCloud, avatars, a rating line). |
| `media?` | `React.ReactNode` |  | Media slot: end column for `split`, below the copy for `stacked-media`. |
| `primaryAction?` | `HeroAction` |  |  |
| `secondaryAction?` | `HeroAction` |  |  |
| `title` | `React.ReactNode` |  | Headline, rendered as the page level heading. |
| `variant?` | `BlockLook \| "default" \| null` |  | Block shell. Omit for the ambient style: glinr (open canvas), plain, or glass panel. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`.

## Accessibility

- A `section` labelled by the headline, which is the page h1 by default.
- Decorative background is aria-hidden.
- Announcement link and actions keep visible focus rings.

ARIA:

- `aria-labelledby` points at the headline
- `aria-hidden` on the background layer

- Reduced motion: Entrance reveals and the copy blur-slide follow the Glin motion level. At level none or prefers-reduced-motion everything renders in its final static state.

---

# Feature Grid

> Icon-framed feature cards in three-up, bento, icon-list and alternating-row layouts.

- id: `feature-grid`
- type: primitive
- category: Blocks
- tags: primitive
- docs: https://glinui.com/docs/components/radix/feature-grid
- markdown: https://glinui.com/md/feature-grid.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add feature-grid
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/feature-grid.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { FeatureGrid, GlinProvider, SURFACE_VARIANTS, SURFACE_TONES, SURFACE_ELEVATIONS, SURFACE_VARIANT_ALIASES, STYLE_DEFAULT_VARIANT, GLIN_MOTIONS } from "@glinui/ui"
```

## Usage

Own design from Card, IconFrame, Heading and Text. The `bento` layout composes BentoGrid for the grid and uses Card tiles with repeating spans; it does not duplicate BentoCard.

Icons are nodes (Phosphor elements work). They are decorative and wrapped in an IconFrame.

Six cards in a responsive 1, 2, 3 column grid.

```tsx
import { FeatureGrid } from "@glinui/ui"
import { Gauge } from "@phosphor-icons/react/dist/ssr"

<FeatureGrid
  eyebrow="Why Glin"
  title="Everything a landing page needs"
  features={[{ icon: <Gauge weight="duotone" />, title: "Fast", description: "Server first.", href: "/fast" }]}
/>
```

### Variants

Bento, icon list and alternating rows.

```tsx
<FeatureGrid layout="bento" features={features} />
<FeatureGrid layout="icon-list" features={features} />
<FeatureGrid layout="alternating-rows" features={features} />
```

## Props

### FeatureGridProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `description?` | `React.ReactNode` |  |  |
| `eyebrow?` | `React.ReactNode` |  |  |
| `features` | `FeatureItem[]` |  |  |
| `headingLevel?` | `2 \| 3` | `2` | Level of the section heading. Cards use the next level. Default 2. |
| `layout?` | `FeatureGridLayout` | `"three-up"` |  |
| `title?` | `React.ReactNode` |  |  |
| `variant?` | `BlockLook \| "default" \| null` |  | Block shell: glinr (open), plain, glass panel. Omit for the ambient style. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`.

## Accessibility

- A `section` labelled by its heading with headings in order.
- Rows and icon lists are semantic lists.
- Card links are real anchors with focus rings.

ARIA:

- `aria-labelledby` on the section
- `aria-hidden` on icon frames

- Reduced motion: Entrance reveals and the card hover lift follow the Glin motion level. At level none or prefers-reduced-motion everything renders in its final static state.

---

# Pricing Section

> Tier cards with monthly or yearly switch, highlighted plan, check lists and a comparison table layout.

- id: `pricing-section`
- type: primitive
- category: Blocks
- tags: primitive
- docs: https://glinui.com/docs/components/radix/pricing-section
- markdown: https://glinui.com/md/pricing-section.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add pricing-section
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/pricing-section.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { PricingSection, GlinProvider, SURFACE_VARIANTS, SURFACE_TONES, SURFACE_ELEVATIONS, SURFACE_VARIANT_ALIASES, STYLE_DEFAULT_VARIANT, GLIN_MOTIONS } from "@glinui/ui"
```

## Usage

Own design from Card, Switch, Badge, Button, Table and ShineBorder. Prices are numbers formatted with `Intl.NumberFormat`, so currency and locale are props, never hardcoded.

Billing is controlled (`billing`) or uncontrolled (`defaultBilling`), with `onBillingChange` in both cases.

Tier prices are per month for each period. Pass a string such as "Custom" for contact-sales tiers.

Three tiers, a highlighted middle tier and a monthly or yearly switch.

```tsx
import { PricingSection } from "@glinui/ui"

<PricingSection
  title="Simple pricing"
  yearlyNote="Save 20%"
  tiers={[
    { id: "solo", name: "Solo", price: { monthly: 12, yearly: 9 }, features: ["1 workspace"], cta: { label: "Start", href: "/start" } },
    { id: "team", name: "Team", price: { monthly: 32, yearly: 26 }, features: ["Unlimited"], cta: { label: "Trial" }, highlighted: true, badge: "Most popular" }
  ]}
/>
```

### States

Yearly default with euro formatting, and the comparison table layout.

```tsx
<PricingSection tiers={tiers} defaultBilling="yearly" currency="EUR" locale="de-DE" highlightEffect="none" />
<PricingSection tiers={tiers} layout="table" comparison={[{ label: "Audit log", values: [false, true, true] }]} />
```

## Props

### PricingSectionProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `billing?` | `BillingPeriod` |  | Controlled billing period. |
| `comparison?` | `PricingComparisonRow[]` |  |  |
| `currency?` | `string` | `"USD"` | ISO 4217 code for `Intl.NumberFormat`. Default USD. |
| `defaultBilling?` | `BillingPeriod` | `"monthly"` | Initial billing period when uncontrolled. Default `monthly`. |
| `description?` | `React.ReactNode` |  |  |
| `headingLevel?` | `2 \| 3` | `2` |  |
| `hideToggle?` | `boolean` | `false` | Hide the toggle (single period). |
| `highlightEffect?` | `"shine" \| "none"` | `"shine"` | Edge effect on the highlighted card. Default `shine`. |
| `layout?` | `"cards" \| "table"` | `"cards"` | `cards` shows tier cards, `table` a comparison table built from `comparison`. |
| `locale?` | `string` |  | BCP 47 locale for formatting. Default is the runtime locale. |
| `onBillingChange?` | `(billing: BillingPeriod) => void` |  |  |
| `tiers` | `PricingTier[]` |  |  |
| `title?` | `React.ReactNode` |  |  |
| `variant?` | `BlockLook \| "default" \| null` |  |  |
| `yearlyNote?` | `string` |  | Text on the yearly side of the toggle, for example "Save 20%". |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`.

## Accessibility

- The price is an aria-live polite region, so a toggle is announced.
- The switch has the name Bill yearly; the visible Monthly and Yearly labels show the state.
- Features are lists with decorative check icons; the table uses column and row headers and text for included or not included.

Keyboard:

| Key | Action |
| --- | --- |
| Space / Enter | Toggle billing period on the switch |

ARIA:

- `aria-live="polite"` on prices
- `role="switch"` from Switch

- Reduced motion: Entrance reveals and the highlighted shine follow the Glin motion level. At level none or prefers-reduced-motion everything renders in its final static state.

---

# FAQ Section

> Accordion based FAQ with two column or centered layout, category tabs and a FAQPage JSON-LD helper.

- id: `faq-section`
- type: primitive
- category: Blocks
- tags: primitive
- docs: https://glinui.com/docs/components/radix/faq-section
- markdown: https://glinui.com/md/faq-section.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add faq-section
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/faq-section.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { FaqSection } from "@glinui/ui"
```

## Usage

Composes our Accordion, so keyboard and ARIA come from it.

`faqJsonLd(items)` returns an escaped JSON string for a script tag, or pass `jsonLd` to render it. Rich answers need `answerText` to appear in the JSON-LD.

Two column with FAQPage JSON-LD.

```tsx
import { FaqSection, faqJsonLd } from "@glinui/ui"

<FaqSection items={items} title="Questions, answered" jsonLd />
```

### Variants

Centered, and with category tabs.

```tsx
<FaqSection items={items} layout="centered" />
<FaqSection items={items} categories />
```

### States

Single open item by default, `multiple` opens several.

```tsx
<FaqSection items={items} multiple />
```

## Props

### FaqSectionProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `aside?` | `React.ReactNode` |  | Extra content under the title in the two-column layout, such as a contact card. |
| `categories?` | `boolean` | `false` | Group items into category tabs (items need a `category`). |
| `description?` | `React.ReactNode` |  |  |
| `eyebrow?` | `React.ReactNode` |  |  |
| `items` | `FaqItem[]` |  |  |
| `jsonLd?` | `boolean` | `false` | Render a FAQPage JSON-LD script. |
| `layout?` | `FaqSectionLayout` | `"two-column"` |  |
| `multiple?` | `boolean` | `false` | Allow several items open at once. |
| `title?` | `React.ReactNode` |  |  |
| `variant?` | `AccordionVariant` |  | Accordion look. Omit to follow the ambient style. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Section labelled by its heading.
- Accordion triggers are buttons with aria-expanded.
- Category tabs use the tablist pattern with arrow key navigation.

Keyboard:

| Key | Action |
| --- | --- |
| Enter / Space | Toggle the focused question |
| Arrow keys | Move between category tabs |

- Reduced motion: The accordion height animation is removed under reduced motion by the Accordion itself.

---

# CTA Band

> Closing call to action: centered, split with email capture, or boxed with a token glow.

- id: `cta-band`
- type: primitive
- category: Blocks
- tags: primitive
- docs: https://glinui.com/docs/components/radix/cta-band
- markdown: https://glinui.com/md/cta-band.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add cta-band
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/cta-band.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { CtaBand, GlinProvider, SURFACE_VARIANTS, SURFACE_TONES, SURFACE_ELEVATIONS, SURFACE_VARIANT_ALIASES, STYLE_DEFAULT_VARIANT, GLIN_MOTIONS } from "@glinui/ui"
```

## Usage

The glow uses the `--glow-a` and `--glow-b` tokens (no rainbow). Pass `background` to place a gradient mesh or aurora behind the content.

Boxed with a token glow.

```tsx
<CtaBand layout="boxed-gradient" title="Ship it" primary={{ label: "Get started", href: "/start" }} />
```

### Variants

Centered, split with email capture, plain shell.

```tsx
<CtaBand layout="split" title="Join" emailCapture={{ onSubmit }} />
```

### States

Glow can be forced on any layout with `glow`.

```tsx
<CtaBand glow title="Glow" />
```

## Props

### CtaBandProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `background?` | `React.ReactNode` |  | Decorative background slot such as a gradient mesh. Rendered aria-hidden behind the content. |
| `description?` | `React.ReactNode` |  |  |
| `emailCapture?` | `CtaEmailCapture` |  | Built-in email capture form (the split layout shows it in place of the actions). |
| `eyebrow?` | `React.ReactNode` |  |  |
| `footnote?` | `React.ReactNode` |  | Free slot under the actions, for a custom form or fine print. |
| `glow?` | `boolean` |  | Soft token glow behind the content. On by default for `boxed-gradient`. |
| `layout?` | `CtaBandLayout` | `"centered"` |  |
| `primary?` | `CtaAction` |  |  |
| `secondary?` | `CtaAction` |  |  |
| `title` | `React.ReactNode` |  |  |
| `variant?` | `BlockVariant` |  | Shell look. Omit to follow the ambient style. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Section labelled by its heading.
- Email input has a screen reader label and autocomplete.
- Glow and background are aria-hidden and hidden in forced colors.
- Reduced motion: The band is static, there is no animation.

---

# Footer Block

> Site footer with link groups, brand and newsletter slots, social icons, legal row and theme toggle slot.

- id: `footer-block`
- type: primitive
- category: Blocks
- tags: primitive
- docs: https://glinui.com/docs/components/radix/footer-block
- markdown: https://glinui.com/md/footer-block.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add footer-block
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/footer-block.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { FooterBlock, GlinProvider, SURFACE_VARIANTS, SURFACE_TONES, SURFACE_ELEVATIONS, SURFACE_VARIANT_ALIASES, STYLE_DEFAULT_VARIANT, GLIN_MOTIONS } from "@glinui/ui"
```

## Usage

Links render plain anchors; target blank links get `noopener noreferrer` automatically. Columns use logical layout, so RTL flips the order.

Columns with newsletter, social, legal and theme slot.

```tsx
<FooterBlock brand={<Logo />} groups={groups} newsletter={{ onSubmit }} social={social} />
```

### Variants

Minimal row and big wordmark.

```tsx
<FooterBlock layout="minimal" groups={groups} />
<FooterBlock layout="big-wordmark" wordmark="Acme" />
```

### States

Newsletter and social slots are optional.

```tsx
<FooterBlock groups={groups} />
```

## Props

### FooterBlockProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `brand?` | `React.ReactNode` |  | Logo, name and tagline. |
| `copyright?` | `React.ReactNode` |  | Copyright line. |
| `groups?` | `FooterLinkGroup[]` | `[]` |  |
| `layout?` | `FooterBlockLayout` | `"columns"` |  |
| `legal?` | `FooterLink[]` |  | Legal links such as Privacy and Terms. |
| `newsletter?` | `FooterNewsletter` |  |  |
| `social?` | `FooterSocial[]` |  |  |
| `themeToggle?` | `React.ReactNode` |  | Slot for a theme toggle. |
| `variant?` | `BlockVariant` |  | Surface look. Omit to follow the ambient style. `glass` is opt-in and needs a backdrop. |
| `wordmark?` | `string` |  | Oversized text for the `big-wordmark` layout. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- `footer` landmark.
- Each group is a `nav` labelled by its title.
- Icon only social links require an accessible label.
- Newsletter input has a screen reader label.
- Reduced motion: No animation, only color transitions that are disabled under reduced motion.

---

# Logo Cloud

> Grayscale-to-color logo strip with a marquee option that respects reduced motion.

- id: `logo-cloud`
- type: primitive
- category: Blocks
- tags: primitive
- docs: https://glinui.com/docs/components/radix/logo-cloud
- markdown: https://glinui.com/md/logo-cloud.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add logo-cloud
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/logo-cloud.json
```

Package:

```bash
npm install @glinui/ui @glinui/motion @glinui/tokens
```

## Import

```tsx
import { LogoCloud, LogoWordmark, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider } from "@glinui/ui"
```

## Usage

Own design. Items are ReactNode (or `{ name, logo, href }`), so the block works with any SVG set. The demos use generated text wordmarks; never ship real brand marks without permission.

The marquee reuses Marquee. Looped copies are aria-hidden, so linked items render unlinked there. Use the grid layout when logos must link.

Under reduced motion or motion none the marquee becomes the static grid.

Grayscale wordmarks that turn to full color on hover.

```tsx
import { LogoCloud, LogoWordmark } from "@glinui/ui"

const items = ["Acme", "Nimbus"].map((name) => ({ name, logo: <LogoWordmark>{name}</LogoWordmark> }))

<LogoCloud items={items} title="Trusted by teams at" />
```

### Variants

Marquee with and without faded edges, and a short grid.

```tsx
<LogoCloud layout="marquee" items={items} />
<LogoCloud layout="marquee" fadeEdges={false} grayscale={false} items={items} />
```

## Props

### LogoCloudProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `fadeEdges?` | `boolean` | `true` | Mask the start and end of the marquee. Default true. |
| `grayscale?` | `boolean` | `true` | Grayscale until hover or focus. Default true. |
| `items` | `LogoCloudEntry[]` |  |  |
| `layout?` | `"grid" \| "marquee"` | `"grid"` | `grid` is a static responsive list. `marquee` scrolls (static grid under reduced motion). |
| `listLabel?` | `string` | `"Trusted by"` | Accessible label of the list. Defaults to "Trusted by". |
| `speed?` | `number` | `40` | Seconds for one marquee loop. |
| `title?` | `React.ReactNode` |  | Optional line above the logos. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- The grid is a labelled list.
- Named logos expose `role=img` with the name, or a link with an aria-label.
- The marquee pauses on hover and on keyboard focus.

ARIA:

- `aria-label` on the list or group
- `aria-hidden` on the looped copy

- Reduced motion: Entrance reveals and the marquee scroll follow the Glin motion level. At level none or prefers-reduced-motion everything renders in its final static state.

---

# Testimonials Wall

> Social proof as masonry columns, vertical marquee columns or a single featured quote.

- id: `testimonials-wall`
- type: primitive
- category: Blocks
- tags: primitive
- docs: https://glinui.com/docs/components/radix/testimonials-wall
- markdown: https://glinui.com/md/testimonials-wall.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add testimonials-wall
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/testimonials-wall.json
```

Package:

```bash
npm install @glinui/ui @glinui/motion @glinui/tokens
```

## Import

```tsx
import { TestimonialsWall, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider, GlinProvider, SURFACE_VARIANTS, SURFACE_TONES, SURFACE_ELEVATIONS } from "@glinui/ui"
```

## Usage

Own design, no photos: avatars are initials. Demo names and quotes are placeholders, never real people.

marquee-columns scrolls two columns in opposite directions with the Web Animations API. Hovering or focusing a column pauses it. With reduced motion or motion level none the columns render static and complete.

Masonry columns, 1 to 3 wide.

```tsx
import { TestimonialsWall } from "@glinui/ui"

<TestimonialsWall items={items} title="What builders say" />
```

### Variants

Marquee columns and a featured quote.

```tsx
<TestimonialsWall items={items} layout="marquee-columns" />
<TestimonialsWall items={items} layout="single-quote" />
```

### States

Plain shell.

```tsx
<TestimonialsWall items={items} variant="plain" />
```

## Props

### TestimonialsWallProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `description?` | `React.ReactNode` |  |  |
| `duration?` | `number` | `40` | Seconds for one marquee loop. |
| `eyebrow?` | `React.ReactNode` |  |  |
| `items` | `TestimonialItem[]` |  |  |
| `layout?` | `TestimonialsWallLayout` | `"masonry-columns"` |  |
| `title?` | `React.ReactNode` |  |  |
| `variant?` | `BlockVariant` |  | Shell look of the cards. Omit to follow the ambient style. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- A `section` labelled by its heading.
- Each quote is a figure with blockquote and cite.
- Ratings are `role="img"` with a text label.
- The marquee copy is aria-hidden and inert, so screen readers read each quote once.

ARIA:

- `aria-labelledby` on the section
- `aria-label="Rated N out of 5"` on stars

- Reduced motion: No scrolling and no WAAPI animation. Columns show every quote in normal flow.

---

# Message

> Chat turn layout with roles, avatar, bubble content and an actions toolbar (copy, regenerate, feedback).

- id: `message`
- type: primitive
- category: AI
- tags: primitive
- docs: https://glinui.com/docs/components/radix/message
- markdown: https://glinui.com/md/message.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add message
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/message.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Message, MessageAvatar, MessageContent, MessageActions, MessageAction, MessageCopyAction } from "@glinui/ui"
```

## Usage

Avatars, attachments, a finished reply with actions, a streaming reply and a thinking indicator, above a prompt input.

```tsx
import { ArrowsClockwise, Paperclip, ThumbsDown, ThumbsUp } from "@phosphor-icons/react"
import {
  Attachment, Badge, Heading, Message, MessageAction, MessageActions, MessageAvatar, MessageContent,
  MessageCopyAction, MessageScroller, PromptInput, StreamingText, Text, Thinking
} from "@glinui/ui"

const reply = "Revenue grew 12% quarter over quarter, driven mostly by the Pro plan. Churn stayed flat at 1.8%, so the gain came from expansion rather than new logos."

export function ChatScreen() {
  return (
    <div className="flex h-[34rem] w-full max-w-2xl flex-col overflow-hidden rounded-2xl border border-[var(--line-soft)] bg-[var(--surface-1)] text-left">
      <header className="flex items-center justify-between gap-3 border-b border-[var(--line-soft)] px-4 py-3">
        <div className="flex flex-col">
          <Heading level={2} size="sm">Q3 revenue review</Heading>
          <Text size="sm" variant="muted">Glin assistant, 3 sources</Text>
        </div>
        <Badge tone="success" variant="soft">Online</Badge>
      </header>
      <MessageScroller label="Conversation" className="min-h-0 flex-1">
        <Message role="user">
          <MessageAvatar fallback="MK" alt="" />
          <MessageContent>
            <div className="flex flex-col gap-2">
              <span>Summarize how Q3 went compared with Q2.</span>
              <div className="flex flex-wrap gap-2">
                <Attachment name="q3-revenue.csv" size={48210} />
                <Attachment name="board-notes.pdf" size={1203400} />
              </div>
            </div>
          </MessageContent>
        </Message>
        <Message role="assistant">
          <MessageAvatar fallback="G" alt="" />
          <MessageContent
            actions={
              <MessageActions>
                <MessageCopyAction value={reply} />
                <MessageAction label="Regenerate"><ArrowsClockwise /></MessageAction>
                <MessageAction label="Good response" pressed><ThumbsUp /></MessageAction>
                <MessageAction label="Bad response"><ThumbsDown /></MessageAction>
              </MessageActions>
            }
          >
            <div className="flex flex-col gap-2">
              <Thinking active={false} doneLabel="Thought for 4 seconds">Compared monthly totals, then split growth into new and expansion revenue.</Thinking>
              <span>{reply}</span>
            </div>
          </MessageContent>
        </Message>
        <Message role="user">
          <MessageAvatar fallback="MK" alt="" />
          <MessageContent>Which regions grew fastest?</MessageContent>
        </Message>
        <Message role="assistant">
          <MessageAvatar fallback="G" alt="" />
          <MessageContent>
            <StreamingText text="Europe led with 19% growth, followed by North America at 11%. APAC was flat after the pricing change in August." speed={30} />
          </MessageContent>
        </Message>
        <Message role="assistant">
          <MessageAvatar fallback="G" alt="" />
          <MessageContent><Thinking /></MessageContent>
        </Message>
      </MessageScroller>
      <div className="border-t border-[var(--line-soft)] p-3">
        <PromptInput
          placeholder="Ask a follow up"
          maxLength={500}
          onSubmit={(value) => console.log(value)}
          actions={<MessageAction label="Attach file"><Paperclip /></MessageAction>}
        />
      </div>
    </div>
  )
}
```

### Variants

Every vocabulary variant on the default tone. Omit variant to follow the ambient design style.

```tsx
import { Message, MessageContent } from "@glinui/ui"

export function MessageVariantsDemo() {
  return (
    <div className="grid gap-2 md:grid-cols-2">
      <Message variant="glinr"><MessageContent>glinr bubble</MessageContent></Message>
      <Message variant="solid"><MessageContent>solid bubble</MessageContent></Message>
      <Message variant="plain"><MessageContent>plain bubble</MessageContent></Message>
      <Message variant="soft"><MessageContent>soft bubble</MessageContent></Message>
      <Message variant="outline"><MessageContent>outline bubble</MessageContent></Message>
      <Message variant="ghost"><MessageContent>ghost bubble</MessageContent></Message>
      <Message variant="gradient"><MessageContent>gradient bubble</MessageContent></Message>
    </div>
  )
}
```

### Glass (opt-in)

Glass is opt-in and needs a backdrop behind it. Switch the preview stage to Vivid or Photo to see the frosted surface.

```tsx
import { Message, MessageAvatar, MessageContent } from "@glinui/ui"

export function Demo() {
  return (
    <div className="w-full max-w-lg">
      <Message variant="glass"><MessageAvatar fallback="G" /><MessageContent>First line</MessageContent></Message>
      <Message variant="glass" grouped><MessageAvatar fallback="G" /><MessageContent>Second line, grouped</MessageContent></Message>
    </div>
  )
}
```

## Props

### MessageActionProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | `"Copy message"` | Accessible name, also used as the native tooltip. |
| `pressed?` | `boolean` |  | Toggle state for stateful actions such as thumbs up. |

### MessageContentProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `actions?` | `React.ReactNode` |  | Rendered under the bubble, typically `MessageActions`. |
| `bare?` | `boolean` | `false` | Render children without a bubble (plain assistant prose). |

### MessageCopyActionProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label?` | `string` | `"Copy message"` |  |
| `onCopy?` | `(value: string) => void` |  |  |
| `pressed?` | `boolean` |  | Toggle state for stateful actions such as thumbs up. |
| `resetAfter?` | `number` | `1500` | How long the success state shows, in ms. |
| `value` | `string` |  |  |

### MessageProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `grouped?` | `boolean` | `false` | Stacked message from the same sender: tighter spacing and corners. |
| `role?` | `MessageRole` | `"assistant"` |  |
| `variant?` | `BubbleVariant` |  | Surface treatment passed down to the assistant bubble. Omit for the ambient design style (glinr by default). Vocabulary: glinr, solid, pl... |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Pure presentation: roles are conveyed through layout, so place messages inside MessageScroller (role="log").
- Action buttons always have an aria-label; toggles expose aria-pressed.
- Copy confirmation is announced through a polite status region.
- Layout uses logical properties, so it mirrors correctly in RTL.

Keyboard:

| Key | Action |
| --- | --- |
| Tab | Move through the actions toolbar buttons. |
| Enter / Space | Activate the focused action. |

ARIA:

- `role="toolbar"` with `aria-label="Message actions"`
- `aria-pressed` on toggle actions
- `role="status"` copy confirmation

- Reduced motion: Only opacity and color transitions are used, and they are disabled under reduced motion.

---

# Bubble

> Chat bubble surface with default, muted, accent and glass variants, optional tail and grouped spacing.

- id: `bubble`
- type: primitive
- category: AI
- tags: primitive
- docs: https://glinui.com/docs/components/radix/bubble
- markdown: https://glinui.com/md/bubble.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add bubble
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/bubble.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Bubble, SURFACE_VARIANTS, SURFACE_TONES, SURFACE_ELEVATIONS, SURFACE_VARIANT_ALIASES, STYLE_DEFAULT_VARIANT, GlinProvider, GLIN_MOTIONS } from "@glinui/ui"
```

## Usage

Grouped bubbles share a corner; the last one in a run carries the tail.

```tsx
import { Bubble } from "@glinui/ui"

export function Thread() {
  return (
    <div className="flex w-full max-w-md flex-col gap-1 rounded-2xl border border-[var(--line-soft)] bg-[var(--surface-1)] p-4">
      <Bubble align="start" grouped>Hi, your order shipped this morning.</Bubble>
      <Bubble align="start" tail>It should arrive by Thursday.</Bubble>
      <Bubble align="end" variant="accent" grouped>Great, can I change the address?</Bubble>
      <Bubble align="end" variant="accent" tail>It is the old one on Pine Street.</Bubble>
      <Bubble align="start" variant="muted" tail>Yes, until it reaches the depot. Sending a link now.</Bubble>
    </div>
  )
}
```

### Inside a chat screen

Message wraps Bubble; this is the full screen.

```tsx
import { ArrowsClockwise, Paperclip, ThumbsDown, ThumbsUp } from "@phosphor-icons/react"
import {
  Attachment, Badge, Heading, Message, MessageAction, MessageActions, MessageAvatar, MessageContent,
  MessageCopyAction, MessageScroller, PromptInput, StreamingText, Text, Thinking
} from "@glinui/ui"

const reply = "Revenue grew 12% quarter over quarter, driven mostly by the Pro plan. Churn stayed flat at 1.8%, so the gain came from expansion rather than new logos."

export function ChatScreen() {
  return (
    <div className="flex h-[34rem] w-full max-w-2xl flex-col overflow-hidden rounded-2xl border border-[var(--line-soft)] bg-[var(--surface-1)] text-left">
      <header className="flex items-center justify-between gap-3 border-b border-[var(--line-soft)] px-4 py-3">
        <div className="flex flex-col">
          <Heading level={2} size="sm">Q3 revenue review</Heading>
          <Text size="sm" variant="muted">Glin assistant, 3 sources</Text>
        </div>
        <Badge tone="success" variant="soft">Online</Badge>
      </header>
      <MessageScroller label="Conversation" className="min-h-0 flex-1">
        <Message role="user">
          <MessageAvatar fallback="MK" alt="" />
          <MessageContent>
            <div className="flex flex-col gap-2">
              <span>Summarize how Q3 went compared with Q2.</span>
              <div className="flex flex-wrap gap-2">
                <Attachment name="q3-revenue.csv" size={48210} />
                <Attachment name="board-notes.pdf" size={1203400} />
              </div>
            </div>
          </MessageContent>
        </Message>
        <Message role="assistant">
          <MessageAvatar fallback="G" alt="" />
          <MessageContent
            actions={
              <MessageActions>
                <MessageCopyAction value={reply} />
                <MessageAction label="Regenerate"><ArrowsClockwise /></MessageAction>
                <MessageAction label="Good response" pressed><ThumbsUp /></MessageAction>
                <MessageAction label="Bad response"><ThumbsDown /></MessageAction>
              </MessageActions>
            }
          >
            <div className="flex flex-col gap-2">
              <Thinking active={false} doneLabel="Thought for 4 seconds">Compared monthly totals, then split growth into new and expansion revenue.</Thinking>
              <span>{reply}</span>
            </div>
          </MessageContent>
        </Message>
        <Message role="user">
          <MessageAvatar fallback="MK" alt="" />
          <MessageContent>Which regions grew fastest?</MessageContent>
        </Message>
        <Message role="assistant">
          <MessageAvatar fallback="G" alt="" />
          <MessageContent>
            <StreamingText text="Europe led with 19% growth, followed by North America at 11%. APAC was flat after the pricing change in August." speed={30} />
          </MessageContent>
        </Message>
        <Message role="assistant">
          <MessageAvatar fallback="G" alt="" />
          <MessageContent><Thinking /></MessageContent>
        </Message>
      </MessageScroller>
      <div className="border-t border-[var(--line-soft)] p-3">
        <PromptInput
          placeholder="Ask a follow up"
          maxLength={500}
          onSubmit={(value) => console.log(value)}
          actions={<MessageAction label="Attach file"><Paperclip /></MessageAction>}
        />
      </div>
    </div>
  )
}
```

### Variants

```tsx
import { Bubble } from "@glinui/ui"

export function Demo() {
  return (
    <div className="flex flex-col items-start gap-2">
      <Bubble>Default surface</Bubble>
      <Bubble variant="muted">Muted</Bubble>
      <Bubble variant="accent">Accent</Bubble>
      <Bubble variant="soft">Glass</Bubble>
    </div>
  )
}
```

## Props

### BubbleProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align?` | `"start" \| "end"` |  |  |
| `grouped?` | `boolean` | `false` | Tightens the aligned edge so stacked bubbles read as one group. |
| `tail?` | `boolean` | `false` | Squares the corner nearest the avatar to point at the sender. |
| `tone?` | `SurfaceTone` |  |  |
| `variant?` | `BubbleVariant` |  | Visual variant. Omit for the ambient design style (glinr: raised ringed bubble; plain: flat bordered bubble). Vocabulary: glinr, solid, p... |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Renders a plain div with no implicit role, so content stays readable inside a log region.
- Accent text uses the accent-foreground token for AA contrast in light and dark.
- Long words wrap instead of overflowing.
- Reduced motion: Bubble has no motion of its own.

---

# Message Scroller

> Conversation log that sticks to the bottom, shows a jump to latest pill and announces new messages politely.

- id: `message-scroller`
- type: primitive
- category: AI
- tags: primitive
- docs: https://glinui.com/docs/components/radix/message-scroller
- markdown: https://glinui.com/md/message-scroller.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add message-scroller
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/message-scroller.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { MessageScroller } from "@glinui/ui"
```

## Usage

MessageScroller keeps the log pinned to the newest turn and shows a jump pill when you scroll up.

```tsx
import { ArrowsClockwise, Paperclip, ThumbsDown, ThumbsUp } from "@phosphor-icons/react"
import {
  Attachment, Badge, Heading, Message, MessageAction, MessageActions, MessageAvatar, MessageContent,
  MessageCopyAction, MessageScroller, PromptInput, StreamingText, Text, Thinking
} from "@glinui/ui"

const reply = "Revenue grew 12% quarter over quarter, driven mostly by the Pro plan. Churn stayed flat at 1.8%, so the gain came from expansion rather than new logos."

export function ChatScreen() {
  return (
    <div className="flex h-[34rem] w-full max-w-2xl flex-col overflow-hidden rounded-2xl border border-[var(--line-soft)] bg-[var(--surface-1)] text-left">
      <header className="flex items-center justify-between gap-3 border-b border-[var(--line-soft)] px-4 py-3">
        <div className="flex flex-col">
          <Heading level={2} size="sm">Q3 revenue review</Heading>
          <Text size="sm" variant="muted">Glin assistant, 3 sources</Text>
        </div>
        <Badge tone="success" variant="soft">Online</Badge>
      </header>
      <MessageScroller label="Conversation" className="min-h-0 flex-1">
        <Message role="user">
          <MessageAvatar fallback="MK" alt="" />
          <MessageContent>
            <div className="flex flex-col gap-2">
              <span>Summarize how Q3 went compared with Q2.</span>
              <div className="flex flex-wrap gap-2">
                <Attachment name="q3-revenue.csv" size={48210} />
                <Attachment name="board-notes.pdf" size={1203400} />
              </div>
            </div>
          </MessageContent>
        </Message>
        <Message role="assistant">
          <MessageAvatar fallback="G" alt="" />
          <MessageContent
            actions={
              <MessageActions>
                <MessageCopyAction value={reply} />
                <MessageAction label="Regenerate"><ArrowsClockwise /></MessageAction>
                <MessageAction label="Good response" pressed><ThumbsUp /></MessageAction>
                <MessageAction label="Bad response"><ThumbsDown /></MessageAction>
              </MessageActions>
            }
          >
            <div className="flex flex-col gap-2">
              <Thinking active={false} doneLabel="Thought for 4 seconds">Compared monthly totals, then split growth into new and expansion revenue.</Thinking>
              <span>{reply}</span>
            </div>
          </MessageContent>
        </Message>
        <Message role="user">
          <MessageAvatar fallback="MK" alt="" />
          <MessageContent>Which regions grew fastest?</MessageContent>
        </Message>
        <Message role="assistant">
          <MessageAvatar fallback="G" alt="" />
          <MessageContent>
            <StreamingText text="Europe led with 19% growth, followed by North America at 11%. APAC was flat after the pricing change in August." speed={30} />
          </MessageContent>
        </Message>
        <Message role="assistant">
          <MessageAvatar fallback="G" alt="" />
          <MessageContent><Thinking /></MessageContent>
        </Message>
      </MessageScroller>
      <div className="border-t border-[var(--line-soft)] p-3">
        <PromptInput
          placeholder="Ask a follow up"
          maxLength={500}
          onSubmit={(value) => console.log(value)}
          actions={<MessageAction label="Attach file"><Paperclip /></MessageAction>}
        />
      </div>
    </div>
  )
}
```

## Props

### MessageScrollerProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `jumpLabel?` | `string` | `"Jump to latest"` | Label of the jump pill. |
| `label?` | `string` | `"Conversation"` | Accessible name of the log region. |
| `onAtBottomChange?` | `(atBottom: boolean) => void` |  | Fires when the stuck-to-bottom state flips. |
| `threshold?` | `number` | `80` | Distance in px from the bottom that still counts as "at the bottom". |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Scroll container is role="log" with aria-live="polite" so new messages are announced without interrupting.
- The container is focusable so keyboard users can scroll with arrow keys, Page Up and Page Down.
- Autoscroll only follows while the reader is at the bottom, never yanking them away from history.
- The jump pill is removed from the tab order and accessibility tree while hidden.

Keyboard:

| Key | Action |
| --- | --- |
| Arrow Up / Down | Scroll the focused log. |
| Page Up / Page Down | Scroll by a page. |
| Tab then Enter | Activate Jump to latest when visible. |

ARIA:

- `role="log"`
- `aria-live="polite"`
- `aria-relevant="additions"`
- `aria-hidden` on the hidden jump pill

- Reduced motion: Smooth scrolling is replaced with an instant jump and the pill transition is disabled.

---

# Prompt Input

> Auto-growing chat composer with send and stop, IME-safe Enter handling, attachment slot and character hint.

- id: `prompt-input`
- type: primitive
- category: AI
- tags: primitive
- docs: https://glinui.com/docs/components/radix/prompt-input
- markdown: https://glinui.com/md/prompt-input.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add prompt-input
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/prompt-input.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { PromptInput, CONTROL_LEGACY_VARIANTS, CONTROL_SIZE_CLASSES, GlinProvider, GLIN_MOTIONS, GLIN_ENGINES, GLIN_SURFACES, GLIN_STYLES } from "@glinui/ui"
```

## Usage

A chat composer with removable attachment chips and an attach action.

```tsx
"use client"

import { useState } from "react"
import { Paperclip, Plus } from "@phosphor-icons/react"
import { Attachment, Badge, Button, PromptInput } from "@glinui/ui"

export function PromptComposer() {
  const library = [
    { name: "q3-report.pdf", size: 482000, type: "application/pdf" },
    { name: "metrics.csv", size: 96400, type: "text/csv" },
    { name: "launch-notes.md", size: 7800, type: "text/markdown" }
  ]
  const [files, setFiles] = useState(library.slice(0, 2))
  const [thread, setThread] = useState<string[]>([])
  const next = library.find((file) => !files.some((item) => item.name === file.name))

  return (
    <div className="flex w-full max-w-xl flex-col gap-3">
      {thread.length > 0 ? (
        <ul className="grid gap-2" aria-label="Sent messages">
          {thread.map((message, index) => (
            <li key={`${message}-${index}`} className="ms-auto max-w-[85%] rounded-xl bg-[var(--color-accent)] px-3 py-2 text-sm text-[var(--color-accent-foreground)]">
              {message}
            </li>
          ))}
        </ul>
      ) : null}
      <PromptInput
        label="Message"
        placeholder="Ask about the attached files"
        defaultValue="Summarize the main risks in these files and list three follow-ups."
        attachments={
          files.length > 0 ? (
            <div className="flex flex-wrap gap-2">
              {files.map((file) => (
                <Attachment
                  key={file.name}
                  name={file.name}
                  size={file.size}
                  type={file.type}
                  onRemove={() => setFiles((current) => current.filter((item) => item.name !== file.name))}
                />
              ))}
            </div>
          ) : null
        }
        actions={
          <Button
            type="button"
            variant="ghost"
            size="sm"
            leadingIcon={next ? <Plus weight="bold" /> : <Paperclip weight="bold" />}
            disabled={!next}
            onClick={() => next && setFiles((current) => [...current, next])}
          >
            {next ? "Attach file" : "All files attached"}
          </Button>
        }
        onSubmit={(value) => setThread((current) => [...current, value])}
      />
      <div className="flex items-center gap-2 text-xs text-[var(--color-muted)]">
        <Badge variant="soft" size="sm">{files.length} attached</Badge>
        Press Enter to send, Shift and Enter for a new line.
      </div>
    </div>
  )
}
```

### Variants

```tsx
import { PromptInput } from "@glinui/ui"

export function Demo() {
  return (
    <div className="flex w-full max-w-xl flex-col gap-3">
      <PromptInput variant="glinr" placeholder="glinr" showHint={false} />
      <PromptInput variant="plain" placeholder="plain" showHint={false} />
      <PromptInput variant="soft" placeholder="soft" showHint={false} />
      <PromptInput variant="outline" placeholder="outline" showHint={false} />
    </div>
  )
}
```

### Glass (opt-in)

Glass is opt-in and needs a backdrop behind it: pick Photo or Vivid in the stage backdrop switcher.

```tsx
import { PromptInput } from "@glinui/ui"

export function Demo() {
  return (
    <PromptInput variant="glass" defaultValue="Summarize this thread" />
  )
}
```

## Props

### PromptInputProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `actions?` | `React.ReactNode` |  | Rendered at the start of the footer, e.g. attach and model buttons. |
| `attachments?` | `React.ReactNode` |  | Rendered above the textarea, e.g. a row of `Attachment`. |
| `defaultValue?` | `string` | `""` |  |
| `disabled?` | `boolean` | `false` |  |
| `label?` | `string` | `"Message"` | Accessible name of the textarea. |
| `loading?` | `boolean` | `false` | A response is streaming: input becomes read-only and send is blocked. |
| `maxLength?` | `number` |  |  |
| `onStop?` | `() => void` |  | When set and `loading`, the send button becomes a stop button. |
| `onSubmit?` | `(value: string) => void` |  | Called with the trimmed value when the user sends. |
| `onValueChange?` | `(value: string) => void` |  |  |
| `placeholder?` | `string` | `"Ask anything"` |  |
| `rows?` | `number` | `1` |  |
| `sendLabel?` | `string` | `"Send message"` |  |
| `showHint?` | `boolean` | `true` | Show the keyboard hint and character count. |
| `stopLabel?` | `string` | `"Stop generating"` |  |
| `submitOn?` | `"enter" \| "mod-enter"` | `"enter"` | `enter` sends on Enter (Shift+Enter newline). `mod-enter` sends on Cmd/Ctrl+Enter. |
| `value?` | `string` |  |  |
| `variant?` | `ControlVariantProp` |  | Shell look. Omit to follow the ambient design style (glinr = raised shell). Same vocabulary as Input. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Native textarea with an aria-label and an aria-describedby hint for the send shortcut.
- Enter during an IME composition (Japanese, Chinese, Korean) confirms the text and never sends.
- While loading the field is read-only (focus is kept) and the stop button replaces send.
- Send and stop buttons have explicit labels.

Keyboard:

| Key | Action |
| --- | --- |
| Enter | Send (default mode). |
| Shift + Enter | Insert a new line. |
| Cmd/Ctrl + Enter | Send in mod-enter mode. |

ARIA:

- `aria-label` on the textarea
- `aria-describedby` hint
- `aria-busy` while loading

- Reduced motion: Focus and button transitions are disabled under reduced motion.

---

# Attachment

> File chip or image thumbnail with type icon, size, upload progress and remove button.

- id: `attachment`
- type: primitive
- category: AI
- tags: primitive
- docs: https://glinui.com/docs/components/radix/attachment
- markdown: https://glinui.com/md/attachment.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add attachment
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/attachment.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Attachment, SURFACE_VARIANTS, SURFACE_TONES, SURFACE_ELEVATIONS, SURFACE_VARIANT_ALIASES, STYLE_DEFAULT_VARIANT, GlinProvider, GLIN_MOTIONS } from "@glinui/ui"
```

## Usage

Removable files, an upload at 64 percent and a failed file.

```tsx
import { Attachment, PromptInput, Text } from "@glinui/ui"

export function AttachmentTray() {
  return (
    <div className="flex w-full max-w-xl flex-col gap-3 rounded-2xl border border-[var(--line-soft)] bg-[var(--surface-1)] p-4">
      <Text variant="eyebrow">Attached to this message</Text>
      <div className="flex flex-wrap gap-2">
        <Attachment name="q3-revenue.csv" size={48210} onRemove={() => {}} />
        <Attachment name="board-notes.pdf" size={1203400} onRemove={() => {}} />
        <Attachment name="architecture.png" size={904000} progress={64} />
        <Attachment name="export.zip" size={5400000} tone="danger" />
      </div>
      <PromptInput placeholder="Add a note" onSubmit={(value) => console.log(value)} />
    </div>
  )
}
```

### In a message

Attachments inside a user message.

```tsx
import { ArrowsClockwise, Paperclip, ThumbsDown, ThumbsUp } from "@phosphor-icons/react"
import {
  Attachment, Badge, Heading, Message, MessageAction, MessageActions, MessageAvatar, MessageContent,
  MessageCopyAction, MessageScroller, PromptInput, StreamingText, Text, Thinking
} from "@glinui/ui"

const reply = "Revenue grew 12% quarter over quarter, driven mostly by the Pro plan. Churn stayed flat at 1.8%, so the gain came from expansion rather than new logos."

export function ChatScreen() {
  return (
    <div className="flex h-[34rem] w-full max-w-2xl flex-col overflow-hidden rounded-2xl border border-[var(--line-soft)] bg-[var(--surface-1)] text-left">
      <header className="flex items-center justify-between gap-3 border-b border-[var(--line-soft)] px-4 py-3">
        <div className="flex flex-col">
          <Heading level={2} size="sm">Q3 revenue review</Heading>
          <Text size="sm" variant="muted">Glin assistant, 3 sources</Text>
        </div>
        <Badge tone="success" variant="soft">Online</Badge>
      </header>
      <MessageScroller label="Conversation" className="min-h-0 flex-1">
        <Message role="user">
          <MessageAvatar fallback="MK" alt="" />
          <MessageContent>
            <div className="flex flex-col gap-2">
              <span>Summarize how Q3 went compared with Q2.</span>
              <div className="flex flex-wrap gap-2">
                <Attachment name="q3-revenue.csv" size={48210} />
                <Attachment name="board-notes.pdf" size={1203400} />
              </div>
            </div>
          </MessageContent>
        </Message>
        <Message role="assistant">
          <MessageAvatar fallback="G" alt="" />
          <MessageContent
            actions={
              <MessageActions>
                <MessageCopyAction value={reply} />
                <MessageAction label="Regenerate"><ArrowsClockwise /></MessageAction>
                <MessageAction label="Good response" pressed><ThumbsUp /></MessageAction>
                <MessageAction label="Bad response"><ThumbsDown /></MessageAction>
              </MessageActions>
            }
          >
            <div className="flex flex-col gap-2">
              <Thinking active={false} doneLabel="Thought for 4 seconds">Compared monthly totals, then split growth into new and expansion revenue.</Thinking>
              <span>{reply}</span>
            </div>
          </MessageContent>
        </Message>
        <Message role="user">
          <MessageAvatar fallback="MK" alt="" />
          <MessageContent>Which regions grew fastest?</MessageContent>
        </Message>
        <Message role="assistant">
          <MessageAvatar fallback="G" alt="" />
          <MessageContent>
            <StreamingText text="Europe led with 19% growth, followed by North America at 11%. APAC was flat after the pricing change in August." speed={30} />
          </MessageContent>
        </Message>
        <Message role="assistant">
          <MessageAvatar fallback="G" alt="" />
          <MessageContent><Thinking /></MessageContent>
        </Message>
      </MessageScroller>
      <div className="border-t border-[var(--line-soft)] p-3">
        <PromptInput
          placeholder="Ask a follow up"
          maxLength={500}
          onSubmit={(value) => console.log(value)}
          actions={<MessageAction label="Attach file"><Paperclip /></MessageAction>}
        />
      </div>
    </div>
  )
}
```

### Variants

Every vocabulary variant on the default tone. Omit variant to follow the ambient design style.

```tsx
import { Attachment } from "@glinui/ui"

export function AttachmentVariantsDemo() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <Attachment variant="glinr" name="glinr.pdf" size={24000} />
      <Attachment variant="solid" name="solid.pdf" size={24000} />
      <Attachment variant="plain" name="plain.pdf" size={24000} />
      <Attachment variant="soft" name="soft.pdf" size={24000} />
      <Attachment variant="outline" name="outline.pdf" size={24000} />
      <Attachment variant="ghost" name="ghost.pdf" size={24000} />
      <Attachment variant="gradient" name="gradient.pdf" size={24000} />
    </div>
  )
}
```

## Props

### AttachmentProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `display?` | `"chip" \| "thumbnail"` | `"chip"` | Variant option from attachmentDisplay. |
| `name` | `string` |  |  |
| `onRemove?` | `() => void` |  |  |
| `previewUrl?` | `string` |  | Image URL. With `display="thumbnail"` it fills the tile. |
| `progress?` | `number` |  | 0 to 100. When defined and below 100 a progress bar is shown. |
| `removeLabel?` | `string` |  |  |
| `size?` | `number` |  | Size in bytes. |
| `tone?` | `SurfaceTone` |  |  |
| `type?` | `string` |  | MIME type or extension used to pick the icon. |
| `variant?` | `SurfaceVariant \| "default" \| "raised" \| "frosted"` |  | Visual variant. Omit for the ambient design style (glinr by default). Vocabulary: glinr, solid, plain, soft, outline, ghost, gradient, gl... |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`, `raised`, `frosted`.

## Accessibility

- Upload progress is exposed as role="progressbar" with aria-valuenow.
- The remove button is named "Remove <file name>".
- Thumbnail images use the file name as alt text; chip icons are decorative.

Keyboard:

| Key | Action |
| --- | --- |
| Enter / Space | Activate the remove button. |

ARIA:

- `role="progressbar"` with `aria-valuenow`
- `aria-label` on the remove button

- Reduced motion: Progress width changes animate only when motion is allowed.

---

# Questionnaire

> Multi-step form with single and multiple choice option cards, progress and keyboard accessible radio and checkbox semantics.

- id: `questionnaire`
- type: primitive
- category: AI
- tags: primitive
- docs: https://glinui.com/docs/components/radix/questionnaire
- markdown: https://glinui.com/md/questionnaire.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add questionnaire
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/questionnaire.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Questionnaire, SURFACE_VARIANTS, SURFACE_TONES, SURFACE_ELEVATIONS, SURFACE_VARIANT_ALIASES, STYLE_DEFAULT_VARIANT, GlinProvider, GLIN_MOTIONS } from "@glinui/ui"
```

## Usage

Three steps: single choice cards, another single choice and a multiple choice step, with progress and keyboard radio and checkbox semantics.

```tsx
"use client"

import { useState } from "react"
import { Heading, Questionnaire, Text, type QuestionnaireAnswers } from "@glinui/ui"

const questions = [
  {
    "id": "goal",
    "title": "What are you building?",
    "description": "We use this to pick starter templates.",
    "options": [
      {
        "value": "app",
        "label": "A web app",
        "description": "Dashboards, tools and admin panels"
      },
      {
        "value": "docs",
        "label": "A docs site",
        "description": "Content first, searchable"
      },
      {
        "value": "marketing",
        "label": "A marketing site",
        "description": "Landing pages and campaigns"
      }
    ]
  },
  {
    "id": "team",
    "title": "How big is your team?",
    "options": [
      {
        "value": "solo",
        "label": "Just me"
      },
      {
        "value": "small",
        "label": "2 to 10 people"
      },
      {
        "value": "large",
        "label": "More than 10"
      }
    ]
  },
  {
    "id": "features",
    "title": "Which features do you need first?",
    "type": "multiple",
    "options": [
      {
        "value": "auth",
        "label": "Authentication"
      },
      {
        "value": "billing",
        "label": "Billing"
      },
      {
        "value": "search",
        "label": "Search"
      },
      {
        "value": "ai",
        "label": "AI chat"
      }
    ]
  }
]

export function Onboarding() {
  const [done, setDone] = useState<QuestionnaireAnswers | null>(null)
  return (
    <div className="flex w-full max-w-xl flex-col gap-4 text-left">
      <div className="flex flex-col gap-1">
        <Text variant="eyebrow">Step 1 of 2, account setup</Text>
        <Heading level={2} size="md">Tell us about your project</Heading>
      </div>
      <Questionnaire questions={questions} onSubmit={setDone} submitLabel="Create workspace" />
      {done ? (
        <Text size="sm" variant="muted" role="status">
          Saved: {Object.entries(done).map(([key, value]) => `${key}: ${value.join(", ")}`).join("; ")}
        </Text>
      ) : null}
    </div>
  )
}
```

### Glass (opt-in)

Glass is opt-in and needs a backdrop behind it. Switch the preview stage to Vivid or Photo to see the frosted surface.

```tsx
import { Questionnaire } from "@glinui/ui"

// Same questions as above
export function Demo() {
  return <Questionnaire variant="glass" questions={questions} />
}
```

## Props

### QuestionnaireProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultAnswers?` | `QuestionnaireAnswers` |  |  |
| `onStepChange?` | `(index: number) => void` |  |  |
| `onSubmit?` | `(answers: QuestionnaireAnswers) => void` |  |  |
| `questions` | `QuestionnaireQuestion[]` |  |  |
| `submitLabel?` | `string` | `"Submit"` |  |
| `tone?` | `SurfaceTone` |  |  |
| `variant?` | `SurfaceVariant \| "default" \| "raised" \| "frosted"` |  | Visual variant. Omit for the ambient design style (glinr by default). Vocabulary: glinr, solid, plain, soft, outline, ghost, gradient, gl... |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`, `raised`, `frosted`.

## Accessibility

- Options are native radio or checkbox inputs inside labels, so arrow keys, Space and screen reader semantics come for free.
- Single choice is a radiogroup named by the question; multiple choice is a labelled fieldset.
- Progress is a progressbar with aria-valuetext like "Step 2 of 3".
- Focus moves to the new question heading after Back or Next.

Keyboard:

| Key | Action |
| --- | --- |
| Arrow keys | Move between radio options. |
| Space | Select an option or toggle a checkbox. |
| Enter | Next, or submit on the last step. |

ARIA:

- `role="radiogroup"` for single choice
- `role="progressbar"` with `aria-valuetext`

- Reduced motion: Progress and card transitions are disabled under reduced motion.

---

# Streaming Text

> Progressive text reveal with caret and completion callback, instant under reduced motion.

- id: `streaming-text`
- type: primitive
- category: AI
- tags: primitive
- docs: https://glinui.com/docs/components/radix/streaming-text
- markdown: https://glinui.com/md/streaming-text.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add streaming-text
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/streaming-text.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { StreamingText } from "@glinui/ui"
```

## Usage

The fourth turn streams in with a caret; reduced motion shows it instantly.

```tsx
import { ArrowsClockwise, Paperclip, ThumbsDown, ThumbsUp } from "@phosphor-icons/react"
import {
  Attachment, Badge, Heading, Message, MessageAction, MessageActions, MessageAvatar, MessageContent,
  MessageCopyAction, MessageScroller, PromptInput, StreamingText, Text, Thinking
} from "@glinui/ui"

const reply = "Revenue grew 12% quarter over quarter, driven mostly by the Pro plan. Churn stayed flat at 1.8%, so the gain came from expansion rather than new logos."

export function ChatScreen() {
  return (
    <div className="flex h-[34rem] w-full max-w-2xl flex-col overflow-hidden rounded-2xl border border-[var(--line-soft)] bg-[var(--surface-1)] text-left">
      <header className="flex items-center justify-between gap-3 border-b border-[var(--line-soft)] px-4 py-3">
        <div className="flex flex-col">
          <Heading level={2} size="sm">Q3 revenue review</Heading>
          <Text size="sm" variant="muted">Glin assistant, 3 sources</Text>
        </div>
        <Badge tone="success" variant="soft">Online</Badge>
      </header>
      <MessageScroller label="Conversation" className="min-h-0 flex-1">
        <Message role="user">
          <MessageAvatar fallback="MK" alt="" />
          <MessageContent>
            <div className="flex flex-col gap-2">
              <span>Summarize how Q3 went compared with Q2.</span>
              <div className="flex flex-wrap gap-2">
                <Attachment name="q3-revenue.csv" size={48210} />
                <Attachment name="board-notes.pdf" size={1203400} />
              </div>
            </div>
          </MessageContent>
        </Message>
        <Message role="assistant">
          <MessageAvatar fallback="G" alt="" />
          <MessageContent
            actions={
              <MessageActions>
                <MessageCopyAction value={reply} />
                <MessageAction label="Regenerate"><ArrowsClockwise /></MessageAction>
                <MessageAction label="Good response" pressed><ThumbsUp /></MessageAction>
                <MessageAction label="Bad response"><ThumbsDown /></MessageAction>
              </MessageActions>
            }
          >
            <div className="flex flex-col gap-2">
              <Thinking active={false} doneLabel="Thought for 4 seconds">Compared monthly totals, then split growth into new and expansion revenue.</Thinking>
              <span>{reply}</span>
            </div>
          </MessageContent>
        </Message>
        <Message role="user">
          <MessageAvatar fallback="MK" alt="" />
          <MessageContent>Which regions grew fastest?</MessageContent>
        </Message>
        <Message role="assistant">
          <MessageAvatar fallback="G" alt="" />
          <MessageContent>
            <StreamingText text="Europe led with 19% growth, followed by North America at 11%. APAC was flat after the pricing change in August." speed={30} />
          </MessageContent>
        </Message>
        <Message role="assistant">
          <MessageAvatar fallback="G" alt="" />
          <MessageContent><Thinking /></MessageContent>
        </Message>
      </MessageScroller>
      <div className="border-t border-[var(--line-soft)] p-3">
        <PromptInput
          placeholder="Ask a follow up"
          maxLength={500}
          onSubmit={(value) => console.log(value)}
          actions={<MessageAction label="Attach file"><Paperclip /></MessageAction>}
        />
      </div>
    </div>
  )
}
```

## Props

### StreamingTextProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `caret?` | `boolean` | `true` | Show a blinking caret while revealing. |
| `instant?` | `boolean` | `false` | Skip the animation and render everything at once. |
| `onDone?` | `() => void` |  | Called once each time the full text has been revealed. |
| `speed?` | `number` | `24` | Milliseconds per character. |
| `text` | `string` |  |  |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- The full text is present immediately in a visually hidden node, so screen readers do not hear character-by-character noise.
- The animated copy and caret are aria-hidden.
- Under reduced motion the text renders instantly and onDone still fires.
- Reduced motion: Reveal is skipped and the caret blink is disabled.

---

# Thinking

> Reasoning indicator with animated dots or pulsing text and collapsible reasoning details.

- id: `thinking`
- type: primitive
- category: AI
- tags: primitive
- docs: https://glinui.com/docs/components/radix/thinking
- markdown: https://glinui.com/md/thinking.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add thinking
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/thinking.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Thinking } from "@glinui/ui"
```

## Usage

A collapsed reasoning summary on a finished answer and a live indicator at the bottom.

```tsx
import { ArrowsClockwise, Paperclip, ThumbsDown, ThumbsUp } from "@phosphor-icons/react"
import {
  Attachment, Badge, Heading, Message, MessageAction, MessageActions, MessageAvatar, MessageContent,
  MessageCopyAction, MessageScroller, PromptInput, StreamingText, Text, Thinking
} from "@glinui/ui"

const reply = "Revenue grew 12% quarter over quarter, driven mostly by the Pro plan. Churn stayed flat at 1.8%, so the gain came from expansion rather than new logos."

export function ChatScreen() {
  return (
    <div className="flex h-[34rem] w-full max-w-2xl flex-col overflow-hidden rounded-2xl border border-[var(--line-soft)] bg-[var(--surface-1)] text-left">
      <header className="flex items-center justify-between gap-3 border-b border-[var(--line-soft)] px-4 py-3">
        <div className="flex flex-col">
          <Heading level={2} size="sm">Q3 revenue review</Heading>
          <Text size="sm" variant="muted">Glin assistant, 3 sources</Text>
        </div>
        <Badge tone="success" variant="soft">Online</Badge>
      </header>
      <MessageScroller label="Conversation" className="min-h-0 flex-1">
        <Message role="user">
          <MessageAvatar fallback="MK" alt="" />
          <MessageContent>
            <div className="flex flex-col gap-2">
              <span>Summarize how Q3 went compared with Q2.</span>
              <div className="flex flex-wrap gap-2">
                <Attachment name="q3-revenue.csv" size={48210} />
                <Attachment name="board-notes.pdf" size={1203400} />
              </div>
            </div>
          </MessageContent>
        </Message>
        <Message role="assistant">
          <MessageAvatar fallback="G" alt="" />
          <MessageContent
            actions={
              <MessageActions>
                <MessageCopyAction value={reply} />
                <MessageAction label="Regenerate"><ArrowsClockwise /></MessageAction>
                <MessageAction label="Good response" pressed><ThumbsUp /></MessageAction>
                <MessageAction label="Bad response"><ThumbsDown /></MessageAction>
              </MessageActions>
            }
          >
            <div className="flex flex-col gap-2">
              <Thinking active={false} doneLabel="Thought for 4 seconds">Compared monthly totals, then split growth into new and expansion revenue.</Thinking>
              <span>{reply}</span>
            </div>
          </MessageContent>
        </Message>
        <Message role="user">
          <MessageAvatar fallback="MK" alt="" />
          <MessageContent>Which regions grew fastest?</MessageContent>
        </Message>
        <Message role="assistant">
          <MessageAvatar fallback="G" alt="" />
          <MessageContent>
            <StreamingText text="Europe led with 19% growth, followed by North America at 11%. APAC was flat after the pricing change in August." speed={30} />
          </MessageContent>
        </Message>
        <Message role="assistant">
          <MessageAvatar fallback="G" alt="" />
          <MessageContent><Thinking /></MessageContent>
        </Message>
      </MessageScroller>
      <div className="border-t border-[var(--line-soft)] p-3">
        <PromptInput
          placeholder="Ask a follow up"
          maxLength={500}
          onSubmit={(value) => console.log(value)}
          actions={<MessageAction label="Attach file"><Paperclip /></MessageAction>}
        />
      </div>
    </div>
  )
}
```

## Props

### ThinkingProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `active?` | `boolean` | `true` | True while the model is working. False renders the finished label. |
| `children?` | `React.ReactNode` |  | Reasoning details. When provided the header becomes a disclosure button. |
| `defaultOpen?` | `boolean` | `false` |  |
| `doneLabel?` | `string` | `"Thought process"` | Label once finished, e.g. "Thought for 4 seconds". |
| `indicator?` | `"dots" \| "shimmer"` | `"dots"` | Indicator style while active. |
| `label?` | `string` | `"Thinking"` |  |
| `onOpenChange?` | `(open: boolean) => void` |  |  |
| `open?` | `boolean` |  |  |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Active state without details is a role="status" element so assistive tech announces it.
- With details the header is a native button using aria-expanded and aria-controls.
- Dots are decorative (aria-hidden); the label carries the meaning.

Keyboard:

| Key | Action |
| --- | --- |
| Enter / Space | Toggle the reasoning details. |

ARIA:

- `role="status"` while active
- `aria-expanded` and `aria-controls` on the toggle

- Reduced motion: Pulse animation is removed under reduced motion. Dots stay visible at reduced opacity.

---

# Reveal

> Scroll-triggered entrance with fade, slide, blur and scale variants, driven by a pluggable animation engine (css, motion or gsap).

- id: `reveal`
- type: primitive
- category: Motion
- tags: primitive
- docs: https://glinui.com/docs/components/radix/reveal
- markdown: https://glinui.com/md/reveal.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add reveal
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/reveal.json
```

Package:

```bash
npm install @glinui/ui @glinui/motion @glinui/tokens
```

## Import

```tsx
import { Reveal, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider } from "@glinui/ui"
```

## Usage

```tsx
import { Button, Card, Reveal } from "@glinui/ui"

export function Demo() {
  return (
    <div className="mx-auto flex max-w-xl flex-col gap-3 p-6">
      <Reveal variant="blur-slide" immediate>
        <h2 className="text-2xl font-semibold tracking-tight">Welcome back, Priya</h2>
      </Reveal>
      <Reveal variant="slide" immediate delay={120}>
        <Card className="p-4 text-sm">You have 3 reviews waiting and one deploy in progress.</Card>
      </Reveal>
      <Reveal variant="scale" immediate delay={240}>
        <Button>Open inbox</Button>
      </Reveal>
    </div>
  )
}
```

### Motion engine

```tsx
// pnpm add motion (separate dependency, optional)
// Once at your app entry:
import "@glinui/motion/register/motion"

import { Reveal } from "@glinui/ui"

export function Demo() {
  return (
    <Reveal engine="motion" variant="blur-slide" className="rounded-card border border-line-soft bg-surface-1 p-4">
      Revealed when it scrolls into view.
    </Reveal>
  )
}
```

### GSAP engine

```tsx
// pnpm add gsap (separate dependency under GreenSock's own license, not bundled by GLINUI)
// Once at your app entry:
import "@glinui/motion/register/gsap"

import { Reveal } from "@glinui/ui"

export function Demo() {
  return (
    <Reveal engine="gsap" variant="blur-slide" className="rounded-card border border-line-soft bg-surface-1 p-4">
      Revealed when it scrolls into view.
    </Reveal>
  )
}
```

## Props

### EngineControlProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `engine?` | `EngineName` |  | Engine override: `css` (default), `motion`, `gsap` or a registered custom engine. |
| `motion?` | `MotionLevel` |  | Motion override. `none` renders the static final state, `subtle` is opacity only. |

### RevealProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as?` | `RevealTag` | `"div"` |  |
| `children?` | `React.ReactNode` |  |  |
| `delay?` | `number` |  | Delay in ms. |
| `direction?` | `RevealDirection` |  | Direction the content travels in. Default `up`. |
| `distance?` | `number` |  | Travel distance in px for slide variants. |
| `duration?` | `number` |  | Duration in ms. Defaults to the engine default (520). |
| `engine?` | `EngineName` |  | Engine override: `css` (default), `motion`, `gsap` or a registered custom engine. |
| `immediate?` | `boolean` | `false` | Play on mount instead of waiting for the viewport. |
| `motion?` | `MotionLevel` |  | Motion override. `none` renders the static final state, `subtle` is opacity only. |
| `once?` | `boolean` | `true` | Animate only the first time it enters the viewport. Default true. |
| `spring?` | `SpringInput` |  |  |
| `threshold?` | `number` |  | Visible fraction (0 to 1) required to trigger. Default 0.15. |
| `variant?` | `RevealVariant` | `"slide"` |  |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Content is in the DOM and visible to assistive tech before and after the animation.
- Animation never gates meaning: the static state is identical to the final animated state.
- Reduced motion: Under prefers-reduced-motion the engine drops travel, blur and scale and only fades opacity. motion="none" renders the final state immediately and never loads an animation library.

---

# Split Text

> Splits text into characters, words or lines and animates them in with the active animation engine.

- id: `split-text`
- type: primitive
- category: Motion
- tags: primitive
- docs: https://glinui.com/docs/components/radix/split-text
- markdown: https://glinui.com/md/split-text.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add split-text
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/split-text.json
```

Package:

```bash
npm install @glinui/ui @glinui/motion @glinui/tokens
```

## Import

```tsx
import { SplitText, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider } from "@glinui/ui"
```

## Usage

```tsx
import { SplitText } from "@glinui/ui"

export function Demo() {
  return (
    <div className="mx-auto flex max-w-xl flex-col gap-3 p-6">
      <SplitText as="h2" text="Motion that respects the people using it" immediate className="text-3xl font-bold tracking-tight" />
      <SplitText text="Every effect has a static twin and honors reduced motion." immediate step={25} className="text-sm text-[var(--color-muted)]" />
    </div>
  )
}
```

### Motion engine

```tsx
// pnpm add motion (separate dependency, optional)
// Once at your app entry:
import "@glinui/motion/register/motion"

import { SplitText } from "@glinui/ui"

export function Demo() {
  return <SplitText engine="motion" text="Motion that you can turn off" as="h3" className="type-h3" />
}
```

### GSAP engine

```tsx
// pnpm add gsap (separate dependency under GreenSock's own license, not bundled by GLINUI)
// Once at your app entry:
import "@glinui/motion/register/gsap"

import { SplitText } from "@glinui/ui"

export function Demo() {
  return <SplitText engine="gsap" text="Motion that you can turn off" as="h3" className="type-h3" />
}
```

## Props

### SplitTextProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as?` | `SplitTextTag` | `"p"` |  |
| `by?` | `"words" \| "chars"` | `"words"` | Reveal granularity. Default `words`. |
| `delay?` | `number` |  |  |
| `duration?` | `number` |  |  |
| `engine?` | `EngineName` |  | Engine override: `css` (default), `motion`, `gsap` or a registered custom engine. |
| `immediate?` | `boolean` | `false` |  |
| `motion?` | `MotionLevel` |  | Motion override. `none` renders the static final state, `subtle` is opacity only. |
| `once?` | `boolean` | `true` |  |
| `order?` | `StaggerDirection` | `"forward"` |  |
| `spring?` | `SpringInput` |  |  |
| `step?` | `number` |  | Delay between parts in ms. Default 40 for words and 18 for chars. |
| `text` | `string` |  | The text to split. Plain string only. |
| `threshold?` | `number` |  |  |
| `variant?` | `RevealVariant` | `"blur-slide"` |  |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- The container carries aria-label with the full text and a visually hidden copy, so screen readers read the sentence once.
- Every animated word or character is aria-hidden, which avoids letter-by-letter announcements.

ARIA:

- aria-label on the container
- aria-hidden on the animated parts

- Reduced motion: Under prefers-reduced-motion the engine drops travel, blur and scale and only fades opacity. motion="none" renders the final state immediately and never loads an animation library.

---

# Count Up

> Counts a number up on scroll with the active animation engine, jumping to the end value when motion is off.

- id: `count-up`
- type: primitive
- category: Motion
- tags: primitive
- docs: https://glinui.com/docs/components/radix/count-up
- markdown: https://glinui.com/md/count-up.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add count-up
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/count-up.json
```

Package:

```bash
npm install @glinui/ui @glinui/motion @glinui/tokens
```

## Import

```tsx
import { CountUp, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider } from "@glinui/ui"
```

## Usage

```tsx
import { Card, CountUp } from "@glinui/ui"

export function Demo() {
  return (
    <div className="grid w-full max-w-2xl gap-4 p-4 sm:grid-cols-3">
      <Card className="p-4">
        <p className="text-xs text-[var(--color-muted)]">Downloads this week</p>
        <p className="text-3xl font-semibold"><CountUp value={84200} immediate /></p>
      </Card>
      <Card className="p-4">
        <p className="text-xs text-[var(--color-muted)]">Satisfaction</p>
        <p className="text-3xl font-semibold"><CountUp value={98.6} suffix="%" immediate /></p>
      </Card>
      <Card className="p-4">
        <p className="text-xs text-[var(--color-muted)]">Revenue</p>
        <p className="text-3xl font-semibold"><CountUp value={48920} prefix="$" immediate /></p>
      </Card>
    </div>
  )
}
```

### Motion engine

```tsx
// pnpm add motion (separate dependency, optional)
// Once at your app entry:
import "@glinui/motion/register/motion"

import { CountUp } from "@glinui/ui"

export function Demo() {
  return <CountUp engine="motion" value={12480} suffix="+" className="text-3xl font-semibold" />
}
```

### GSAP engine

```tsx
// pnpm add gsap (separate dependency under GreenSock's own license, not bundled by GLINUI)
// Once at your app entry:
import "@glinui/motion/register/gsap"

import { CountUp } from "@glinui/ui"

export function Demo() {
  return <CountUp engine="gsap" value={12480} suffix="+" className="text-3xl font-semibold" />
}
```

## Props

### CountUpProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `decimals?` | `number` |  |  |
| `delay?` | `number` |  |  |
| `duration?` | `number` |  | Duration in ms. |
| `engine?` | `EngineName` |  | Engine override: `css` (default), `motion`, `gsap` or a registered custom engine. |
| `format?` | `(value: number) => string` |  | Custom formatter. Receives the raw value. Overrides decimals and locale. |
| `from?` | `number` | `0` | Start value. Default 0. |
| `immediate?` | `boolean` | `false` |  |
| `locale?` | `string` |  |  |
| `motion?` | `MotionLevel` |  | Motion override. `none` renders the static final state, `subtle` is opacity only. |
| `once?` | `boolean` | `true` |  |
| `prefix?` | `string` | `""` |  |
| `spring?` | `SpringInput` |  |  |
| `suffix?` | `string` | `""` |  |
| `threshold?` | `number` |  |  |
| `value` | `number` |  | Final value. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Assistive tech always reads the final value: the accessible copy is rendered once and never changes.
- The animating digits are aria-hidden, so there are no repeated announcements.
- The invisible final value reserves the width, so the layout never shifts while counting.
- Reduced motion: Reduced motion and motion="subtle" jump straight to the final number.

---

# Stagger List

> Reveals child items one after another with configurable stagger and direction using the active animation engine.

- id: `stagger-list`
- type: primitive
- category: Motion
- tags: primitive
- docs: https://glinui.com/docs/components/radix/stagger-list
- markdown: https://glinui.com/md/stagger-list.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add stagger-list
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/stagger-list.json
```

Package:

```bash
npm install @glinui/ui @glinui/motion @glinui/tokens
```

## Import

```tsx
import { StaggerList, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider } from "@glinui/ui"
```

## Usage

```tsx
import { StaggerList } from "@glinui/ui"

export function Demo() {
  const steps = ["Create your workspace", "Invite your team", "Connect a repository", "Ship your first release"]
  return (
    <StaggerList as="ol" immediate className="mx-auto flex max-w-sm flex-col gap-2 p-6">
      {steps.map((step, i) => (
        <li key={step} className="flex items-center gap-3 rounded-lg border border-[var(--color-border)] bg-[var(--surface-1)] p-3 text-sm">
          <span className="grid size-6 place-items-center rounded-full bg-[var(--color-accent)] text-xs font-semibold text-[var(--color-accent-foreground)]">{i + 1}</span>
          {step}
        </li>
      ))}
    </StaggerList>
  )
}
```

### Motion engine

```tsx
// pnpm add motion (separate dependency, optional)
// Once at your app entry:
import "@glinui/motion/register/motion"

import { StaggerList } from "@glinui/ui"

export function Demo() {
  return (
    <StaggerList engine="motion" as="ul" step={80} className="space-y-2">
      <li>Design tokens</li>
      <li>Primitives</li>
      <li>Blocks</li>
    </StaggerList>
  )
}
```

### GSAP engine

```tsx
// pnpm add gsap (separate dependency under GreenSock's own license, not bundled by GLINUI)
// Once at your app entry:
import "@glinui/motion/register/gsap"

import { StaggerList } from "@glinui/ui"

export function Demo() {
  return (
    <StaggerList engine="gsap" as="ul" step={80} className="space-y-2">
      <li>Design tokens</li>
      <li>Primitives</li>
      <li>Blocks</li>
    </StaggerList>
  )
}
```

## Props

### StaggerListProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as?` | `StaggerListTag` | `"div"` |  |
| `children?` | `React.ReactNode` |  |  |
| `delay?` | `number` |  |  |
| `direction?` | `RevealDirection` |  |  |
| `distance?` | `number` |  |  |
| `duration?` | `number` |  |  |
| `engine?` | `EngineName` |  | Engine override: `css` (default), `motion`, `gsap` or a registered custom engine. |
| `immediate?` | `boolean` | `false` |  |
| `motion?` | `MotionLevel` |  | Motion override. `none` renders the static final state, `subtle` is opacity only. |
| `once?` | `boolean` | `true` |  |
| `order?` | `StaggerDirection` | `"forward"` | Order the children appear in. Default `forward`. |
| `spring?` | `SpringInput` |  |  |
| `step?` | `number` | `60` | Delay between children in ms. Default 60. |
| `threshold?` | `number` |  |  |
| `variant?` | `RevealVariant` | `"slide"` |  |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Content is in the DOM and visible to assistive tech before and after the animation.
- Animation never gates meaning: the static state is identical to the final animated state.
- List semantics are preserved: render with as="ul" and li children.
- Reduced motion: Under prefers-reduced-motion the engine drops travel, blur and scale and only fades opacity. motion="none" renders the final state immediately and never loads an animation library.

---

# Blur Fade

> Scroll-triggered entrance animation with blur, fade, and slide transitions.

- id: `blur-fade`
- type: signature
- category: Motion
- tags: signature
- docs: https://glinui.com/docs/components/blur-fade
- markdown: https://glinui.com/md/blur-fade.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add blur-fade
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/blur-fade.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { BlurFade, DEFAULT_MOTION_ENGINE_CONFIG, MotionEngineContext, MotionEngineProvider } from "@glinui/ui"
```

## Usage

```tsx
import { BlurFade } from "@glinui/ui"

export function BlurFadeCustomDemo() {
  return (
    <div className="flex flex-col gap-4 p-8">
      <BlurFade blur={20} yOffset={24} duration={700} delay={0}>
        <div className="rounded-xl border border-[var(--color-border)] bg-[var(--surface-2)] p-6">
          <p className="font-semibold">Heavy blur entrance</p>
          <p className="text-sm text-neutral-500">blur={20}, yOffset={24}, duration={700}</p>
        </div>
      </BlurFade>
      <BlurFade blur={20} yOffset={24} duration={700} delay={150}>
        <div className="rounded-xl border border-[var(--color-border)] bg-[var(--surface-2)] p-6">
          <p className="font-semibold">Staggered card</p>
          <p className="text-sm text-neutral-500">delay={150}</p>
        </div>
      </BlurFade>
    </div>
  )
}
```

## Props

### BlurFadeProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `blur?` | `number` | `8` | Initial blur amount (px) |
| `delay?` | `number` | `0` | Delay before transition starts (ms) |
| `duration?` | `number` | `500` | Transition duration (ms) |
| `engine?` | `EngineName` |  | Engine override: `css` (default), `motion`, `gsap` or a registered custom engine. |
| `motion?` | `MotionLevel` |  | Motion override. `none` renders the static final state, `subtle` is opacity only. |
| `once?` | `boolean` | `true` | Only animate once |
| `threshold?` | `number` | `0.1` | IntersectionObserver threshold (0-1) |
| `yOffset?` | `number` | `12` | Initial Y offset (px) |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- Content wrapped by `BlurFade` is fully accessible at all times, only the visual presentation is animated.
- The animation is a progressive enhancement: if JavaScript is unavailable or the `IntersectionObserver` API is not supported, content is shown immediately in its final state.
- Focus and keyboard navigation work normally regardless of animation state.
- Reduced motion: When `prefers-reduced-motion: reduce` is active, `BlurFade` skips the animation entirely and renders content immediately in its final visible state. No blur, no translate, no opacity transition is applied.

---

# Marquee

> Infinite horizontal or vertical scrolling content with pause-on-hover support.

- id: `marquee`
- type: signature
- category: Motion
- tags: signature
- docs: https://glinui.com/docs/components/marquee
- markdown: https://glinui.com/md/marquee.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add marquee
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/marquee.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { Marquee } from "@glinui/ui"
```

## Usage

```tsx
import { Marquee, Badge } from "@glinui/ui"

export function MarqueeVerticalDemo() {
  return (
    <Marquee direction="up" speed={20} gap={8} className="h-48">
      {["Alpha", "Beta", "Gamma", "Delta", "Epsilon"].map((t) => (
        <Badge key={t} variant="outline">{t}</Badge>
      ))}
    </Marquee>
  )
}
```

```tsx
import { Marquee, Badge } from "@glinui/ui"

export function MarqueePauseDemo() {
  return (
    <Marquee pauseOnHover speed={15} gap={24}>
      {["Hover", "to", "pause", "the", "scroll"].map((t) => (
        <Badge key={t} className="mx-2">{t}</Badge>
      ))}
    </Marquee>
  )
}
```

## Props

### MarqueeProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `direction?` | `"left" \| "right" \| "up" \| "down"` | `"left"` |  |
| `gap?` | `number` | `16` | Space between items and between loop copies, in px. |
| `pauseOnHover?` | `boolean` | `false` |  |
| `repeat?` | `number` |  | Fixed number of content copies. By default the marquee measures itself and renders just enough copies to fill the container. |
| `reverse?` | `boolean` | `false` |  |
| `speed?` | `number` | `30` | Seconds for one full loop. |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.

## Accessibility

- The duplicated children are marked `aria-hidden` to prevent screen readers from reading content twice.
- Avoid placing interactive elements inside the marquee.
- Reduced motion: Animation uses `motion-safe:animate-marquee-x/y`. Under `prefers-reduced-motion`, the content stays static.

---

# Orbiting Circles

> CSS-driven orbital animation that keeps children upright via double-rotate.

- id: `orbiting-circles`
- type: signature
- category: Motion
- tags: signature
- docs: https://glinui.com/docs/components/orbiting-circles
- markdown: https://glinui.com/md/orbiting-circles.md

## Install

Glin CLI (copies the source into your project):

```bash
pnpm dlx @glinui/cli@latest add orbiting-circles
```

shadcn CLI:

```bash
npx shadcn@latest add https://glinui.com/r/orbiting-circles.json
```

Package:

```bash
npm install @glinui/ui @glinui/tokens
```

## Import

```tsx
import { OrbitingCircles } from "@glinui/ui"
```

## Usage

```tsx
import { Badge, Button, Heading, OrbitingCircles, Text } from "@glinui/ui"

const inner = ["github", "vercel", "cloudflare"]
const outer = ["react", "typescript", "tailwind", "astro"]

// Replace /logos/<name>.svg with your own marks.
const Logo = ({ name }: { name: string }) => (
  <span className="flex size-9 items-center justify-center rounded-full bg-[var(--surface-2)]"><img src={`/logos/${name}.svg`} alt={name} className="size-5" /></span>
)

export function Integrations() {
  return (
    <section data-glin-theme="dark" className="relative isolate flex w-full flex-col items-center gap-8 overflow-hidden rounded-xl bg-[var(--surface-0)] px-6 py-10 md:flex-row md:justify-between md:px-12">
      <div className="relative z-10 flex max-w-md flex-col gap-4 text-left">
        <Badge tone="accent" variant="soft" className="self-start">40+ integrations</Badge>
        <Heading level={2} size="h2">Plugs into the tools you already run</Heading>
        <Text variant="muted">Connect your repository, hosting and framework once. Deploy hooks, status checks and preview comments appear where your team already works.</Text>
        <div className="flex flex-wrap gap-3"><Button>Browse integrations</Button><Button variant="outline">Request one</Button></div>
      </div>
      <div className="relative flex h-[22rem] w-full max-w-sm items-center justify-center">
        <span className="relative z-10 flex size-14 items-center justify-center rounded-2xl bg-[var(--color-accent)] text-lg font-semibold text-[var(--color-accent-foreground)]">N</span>
        {inner.map((name, index) => (
          <OrbitingCircles key={name} radius={90} duration={24} delay={index * 8} path={index === 0}>
            <Logo name={name} />
          </OrbitingCircles>
        ))}
        {outer.map((name, index) => (
          <OrbitingCircles key={name} radius={150} duration={36} delay={index * 9} reverse path={index === 0}>
            <Logo name={name} />
          </OrbitingCircles>
        ))}
      </div>
    </section>
  )
}
```

```tsx
import { OrbitingCircles } from "@glinui/ui"
import { Lightning, Palette, Sparkle, Globe } from "@phosphor-icons/react"

export function OrbitingCirclesGlassDemo() {
  return (
    <div className="relative flex h-80 w-full items-center justify-center overflow-hidden rounded-xl border border-[var(--color-border)] bg-[var(--surface-1)]">
      <Globe className="size-8 text-neutral-400" />
      <OrbitingCircles variant="glass" iconSize={40} radius={90} duration={16} delay={0} path>
        <Lightning className="size-4 text-neutral-700 dark:text-neutral-300" />
      </OrbitingCircles>
      <OrbitingCircles variant="glass" iconSize={40} radius={90} duration={16} delay={5}>
        <Palette className="size-4 text-neutral-700 dark:text-neutral-300" />
      </OrbitingCircles>
      <OrbitingCircles variant="glass" iconSize={40} radius={90} duration={16} delay={10}>
        <Sparkle className="size-4 text-neutral-700 dark:text-neutral-300" />
      </OrbitingCircles>
    </div>
  )
}
```

```tsx
import { OrbitingCircles } from "@glinui/ui"
import { GitBranch, Database, Cloud, Lock, Shield, Cpu } from "@phosphor-icons/react"

export function OrbitingCircles3DDemo() {
  return (
    <div className="relative flex h-96 w-full items-center justify-center overflow-hidden rounded-xl bg-[linear-gradient(135deg,var(--surface-1),var(--surface-3))]">
      <div className="flex size-14 items-center justify-center rounded-2xl border border-[var(--glass-border)] [border-top-color:var(--glass-refraction-top)] bg-[var(--glass-readable)] [box-shadow:var(--glass-3-shadow)] backdrop-blur-xl">
        <Cpu className="size-6 text-[var(--color-foreground)]" />
      </div>
      {/* Inner ring */}
      <OrbitingCircles variant="3d" iconSize={44} radius={80} duration={18} delay={0} path>
        <GitBranch className="size-5 text-[var(--color-foreground)]" />
      </OrbitingCircles>
      <OrbitingCircles variant="3d" iconSize={44} radius={80} duration={18} delay={6}>
        <Database className="size-5 text-[var(--color-foreground)]" />
      </OrbitingCircles>
      <OrbitingCircles variant="3d" iconSize={44} radius={80} duration={18} delay={12}>
        <Cloud className="size-5 text-[var(--color-foreground)]" />
      </OrbitingCircles>
      {/* Outer ring, reverse */}
      <OrbitingCircles variant="3d" iconSize={40} radius={140} duration={26} delay={0} reverse path>
        <Lock className="size-4 text-[var(--color-muted)]" />
      </OrbitingCircles>
      <OrbitingCircles variant="3d" iconSize={40} radius={140} duration={26} delay={8.5} reverse>
        <Shield className="size-4 text-[var(--color-muted)]" />
      </OrbitingCircles>
      <OrbitingCircles variant="3d" iconSize={40} radius={140} duration={26} delay={17} reverse>
        <Stack className="size-4 text-[var(--color-muted)]" />
      </OrbitingCircles>
    </div>
  )
}
```

## Props

### OrbitingCirclesProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `delay?` | `number` | `0` | Animation delay in seconds |
| `duration?` | `number` | `20` | Full orbit duration in seconds |
| `iconSize?` | `number` | `32` | Size of the orbiting container in px |
| `path?` | `boolean` | `false` | Show orbit path ring |
| `radius?` | `number` | `100` | Orbit radius in px |
| `reverse?` | `boolean` | `false` | Reverse orbit direction |
| `startAngle?` | `number` | `0` | Starting angle in degrees |
| `variant?` | `"default" \| "glass" \| "3d"` | `"default"` | Visual variant |

## Tokens and variants

- Style with CSS variables from `@glinui/tokens` (for example `var(--color-border)`, `var(--color-accent)`, `var(--surface-1)`). Do not hardcode colors.
- Use Tailwind utility classes only. No inline style attributes.
- Use Phosphor icons (`@phosphor-icons/react`) for any icon.
- GLINUI variant vocabulary: solid, soft, outline, ghost, gradient, glass.
- Variants available on this component: `default`, `glass`, `3d`.

## Accessibility

- Each `OrbitingCircles` wrapper is decorative and does not receive keyboard focus.
- Icon children should include `aria-hidden="true"` if they convey no unique information.
- If orbiting elements are meaningful, provide a visible label or `aria-label` on the container.
- Reduced motion: The orbit animation is paused via `motion-reduce:[animation:none]`. All children remain visible at their `startAngle` position so the layout stays intact.