espresso-ui

v0.1.7 — early preview

A small, opinionated UI kit for internal tools.

Carefully-tuned React and Vue components, two themes, and a handful of tokens. Designed for clarity, not flash. Drop into any project; everything ships as copy-pasted source you can override token by token.

Install

Install

Install the CLI globally once, then run init in your project root. It scaffolds the config, drops a base stylesheet, and wires the @ alias. No build configuration needed.

$ npm install -g @espresso-ui/cli

$ espresso-ui init

app.tsx

// after `espresso-ui init`:
import { Button } from "@/components/ui/Button";

export default function App() {
  return <Button>Hello</Button>;
}

Foundations · Color

Color

An 11-step neutral ramp plus five semantic accents. Tokens are mode-aware — switching the theme remaps each step automatically.

Neutrals

11 steps

50

100

200

300

400

500

600

700

800

900

950

Semantic

5 accents

red

amber

green

blue

violet

Foundations · Typography

Typography

Inter for UI, JetBrains Mono for code. Six type roles cover everything from display headlines to inline code.

Display 36px

espresso-ui

H1 24px

Section heading

H2 20px

Subheading

Body 16px

The quick brown fox jumps over the lazy dog.

Body 14px

The quick brown fox jumps over the lazy dog.

Mono 14px

const total = items.length;

Foundations · Spacing

Spacing

A 17-stop scale. Component padding, gaps, and stack rhythm all derive from these tokens.

--spacing-1 1px

--spacing-2 2px

--spacing-3 3px

--spacing-4 4px

--spacing-5 5px

--spacing-6 6px

--spacing-7 7px

--spacing-8 8px

--spacing-9 9px

--spacing-10 10px

--spacing-11 11px

--spacing-12 12px

--spacing-13 14px

--spacing-14 16px

--spacing-15 20px

--spacing-16 24px

--spacing-17 28px

Foundations · Radius

Radius

Rounding stops from sharp corners to fully-pilled. Aliased into semantic radius tokens for component use.

1 4px

2 8px

3 10px

4 12px

5 16px

6 20px

7 22px

full 9999px

Components · Avatar

Avatar

User avatar with image, initials, or icon fallback. Seven sizes and squircle or circle shape. Pass an icon to the status prop (React) or status slot (Vue); Avatar renders the positioned badge shell.

new avatar.tsx Headless API

Preview

initials · icon · image

Shapes squircle vs circle

Sizes xs → 3xl

Content image · initials · icon

Status icon only — badge shell is built in

avatar.tsx

import { Avatar } from "@/components/ui/Avatar";
import { Circle } from "lucide-react";

export default function App() {
  return (
    <Avatar
      fallback="JD"
      size="md"
      shape="circle"
      status={
        <Circle className="size-(--avatar-status-icon-size) fill-green-500 text-green-500" />
      }
    />
  );
}

avatar.vue

<script setup>
import Avatar from "@/components/ui/Avatar.vue";
import { Circle } from "@lucide/vue";
</script>

<template>
  <Avatar fallback="JD" size="md" shape="circle">
    <template #status>
      <Circle class="size-(--avatar-status-icon-size) fill-green-500 text-green-500" />
    </template>
  </Avatar>
</template>

Components · Avatar Group

Avatar Group

Overlapping stack of circular avatars with optional overflow counter and member count label.

new avatar-group.tsx Headless API

Preview

stack · overlap ring

Stack 5 overlapping avatars

Sizes xs → 3xl

Overflow max=4 with 8 items

+4

With label showCount + count

+4

8 members

Content types icon · initials · image

avatar-group.tsx

import { AvatarGroup } from "@/components/ui/AvatarGroup";

export default function App() {
  return (
    <AvatarGroup
      size="md"
      max={4}
      count={8}
      showCount
      items={[
        { fallback: "A" },
        { fallback: "B" },
        { fallback: "C" },
        { fallback: "D" },
        { fallback: "E" },
      ]}
    />
  );
}

avatar-group.vue

<script setup>
import AvatarGroup from "@/components/ui/AvatarGroup.vue";

const items = [
  { fallback: "A" },
  { fallback: "B" },
  { fallback: "C" },
  { fallback: "D" },
  { fallback: "E" },
];
</script>

<template>
  <AvatarGroup size="md" :max="4" :count="8" show-count :items="items" />
</template>

Components · Badge

Badge

Compact status label for counts, alerts, and metadata. Five themes and four variants at three sizes. Prefix and suffix props (React) or slots (Vue) accept icons, spinners, or any inline content.

new badge.tsx Headless API

Preview

solid · subtle · outline · ghost

Label

Active

Failed

Draft

Themes default · error · warning · success · info

Default

Error

Warning

Success

Info

Variants solid · subtle · outline · ghost

Solid

Subtle

Outline

Ghost

Sizes sm · md · lg

Small

Medium

Large

Prefix & suffix icons sized via badge tokens

PrefixBothSuffix

badge.tsx

import { Badge } from "@/components/ui/Badge";
import { Sparkles } from "lucide-react";

export default function App() {
  return (
    <Badge
      theme="success"
      variant="subtle"
      prefix={<Sparkles aria-hidden="true" />}
    >
      Active
    </Badge>
  );
}

badge.vue

<script setup>
import Badge from "@/components/ui/Badge.vue";
import { Sparkles } from "@lucide/vue";
</script>

<template>
  <Badge theme="success" variant="subtle">
    <template #prefix><Sparkles aria-hidden="true" /></template>
    Active
  </Badge>
</template>

Components · Breadcrumb

Breadcrumb

Navigation trail for page hierarchy. Compound API with link, page, separator, and ellipsis parts. Set maxItems on Breadcrumb to auto-collapse middle crumbs into an ellipsis menu (hover or click to reveal). Links use 150ms hover/press feedback and 32px minimum hit targets with invisible expansion. Semantic nav with aria-current on the current page.

new breadcrumb.tsx Headless API

Preview

slash · md · full trail

Separators slash · chevron

Sizes sm · md

Collapse 6 items · maxItems=4 · ellipsis at pos 0 vs 1

Prefix icons Home · Package · Folder · FileText per crumb

maxItems auto-collapse · hover menu · prefix icons

breadcrumb.tsx

import {
  Breadcrumb,
  BreadcrumbList,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbPage,
  BreadcrumbSeparator,
  BreadcrumbEllipsis,
} from "@/components/ui/Breadcrumb";
import { FileText, FolderOpen, Home, Package } from "lucide-react";

export default function App() {
  return (
    // nav landmark + aria-current="page" on BreadcrumbPage are built in
    <Breadcrumb size="md" separator="slash">
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink href="#" prefix={<Home aria-hidden="true" />}>
            Home
          </BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbLink href="#" prefix={<Package aria-hidden="true" />}>
            Products
          </BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbPage prefix={<FileText aria-hidden="true" />}>Current page</BreadcrumbPage>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  );
}

breadcrumb.vue

<script setup>
import Breadcrumb, {
  BreadcrumbList,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbPage,
  BreadcrumbSeparator,
  BreadcrumbEllipsis,
} from "@/components/ui/Breadcrumb.vue";
import { FileText, Home, Package } from "@lucide/vue";
</script>

<template>
  <Breadcrumb size="md" separator="chevron">
    <BreadcrumbList>
      <BreadcrumbItem>
        <BreadcrumbLink href="#">
          <template #prefix><Home aria-hidden="true" /></template>
          Home
        </BreadcrumbLink>
      </BreadcrumbItem>
      <BreadcrumbSeparator />
      <BreadcrumbItem>
        <BreadcrumbLink href="#">
          <template #prefix><Package aria-hidden="true" /></template>
          Products
        </BreadcrumbLink>
      </BreadcrumbItem>
      <BreadcrumbSeparator />
      <BreadcrumbItem>
        <BreadcrumbPage>
          <template #prefix><FileText aria-hidden="true" /></template>
          Current page
        </BreadcrumbPage>
      </BreadcrumbItem>
    </BreadcrumbList>
  </Breadcrumb>
</template>

Components · Button

Button

Primary action control with solid, outline, ghost, and link variants at three sizes. Supports disabled state and asChild composition via Ark UI.

stable button.tsx Headless API

Preview

solid · outline · ghost · link

Sizes 32 / 36 / 40 px

Disabled reduced opacity, no pointer events

button.tsx

import { Button } from "@/components/ui/Button";

export default function App() {
  return (
    <Button variant="solid" size="md">
      Get started
    </Button>
  );
}

Components · Label

Label

Accessible text label for form controls. Pairs with inputs via htmlFor and supports a disabled state that dims the label and blocks pointer events.

stable label.tsx Headless API

Preview

default · disabled

Email address

Disabled label

With input htmlFor association

Full name

label.tsx

import { Label } from "@/components/ui/Label";

export default function App() {
  return <Label htmlFor="email">Email address</Label>;
}

An opinionated UI kit for internal tools.

A small, opinionated UI kit for internal tools.

Install

Color

Neutrals

Semantic

Typography

Spacing

Radius

Avatar

Preview

Avatar Group

Preview

Badge

Preview

Breadcrumb

Preview

Button

Preview

Label

Preview