@glasshome/ui

中文文档
1.40.0发布于 2026/11/16MITTypeScriptES Module构建来源已验证近 30 天下载 3377

SolidJS component library for GlassHome, built on Kobalte

原始使用文档
文档目录9 节
  1. Install
  2. Entry points
  3. @glasshome/ui — utilities and surface recipes
  4. @glasshome/ui/solid — components
  5. @glasshome/ui/tokens — design tokens as data
  6. Astro
  7. @glasshome/ui/styles — Tailwind v4 CSS
  8. Development
  9. License

@glasshome/ui

SolidJS component library for GlassHome, built on Kobalte.

70+ accessible, theme-aware components plus framework-agnostic design tokens and a Tailwind v4 CSS preset, everything you need to build smart-home dashboards. Powers GlassHome, the local-first dashboard for Home Assistant.

The whole library wears a single glass material (.glass with typed --glass-* knobs). SPEC.md is the design-system contract; the live gallery (bun run dev:gallery) is its executable form.

Install

bun add @glasshome/ui solid-js @glasshome/sync-layer
# or
npm install @glasshome/ui solid-js @glasshome/sync-layer

Peer dependencies:

PackageNeeded for
solid-js ^1.9everything under /solid
@glasshome/sync-layer/solid only (EntitySelector, AreaPicker, demo-mode helpers)

The package is ESM-only and ships modern ESM with type declarations that resolve under both bundler and Node 16+ module resolution. Node >=20.

Entry points

@glasshome/ui — utilities and surface recipes

Framework-agnostic root: class-string recipes for the sanctioned glass surfaces, safe to import from server code (e.g. Astro frontmatter) where Solid components cannot run.

import { cn, buttonVariants, CARD_SURFACE, ALERT_TONES, OVERLAY_SURFACE } from "@glasshome/ui";

const cls = cn("px-4 py-2", condition && "text-white");
const btn = buttonVariants({ variant: "outline", size: "sm" });

@glasshome/ui/solid — components

All components are exported from a single subpath.

import { Button, Card, CardHeader, CardTitle, CardContent, Badge } from "@glasshome/ui/solid";

function DeviceCard() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Living Room</CardTitle>
        <Badge tone="var(--success)">Online</Badge>
      </CardHeader>
      <CardContent>
        <Button onClick={() => console.log("toggled")}>Toggle Light</Button>
      </CardContent>
    </Card>
  );
}

Component families: Accordion · Alert · AlertDialog · AreaPicker · AspectRatio · Avatar · Badge · BottomSheet · Breadcrumb · Button · ButtonGroup · Card · Carousel · Charts (AreaChart, BarList, StackedBar, RangeToggle) · Checkbox · Collapsible · ColorSlider · ColorWheel · ContextMenu · CopyButton · CountPill · DataTable (TableSearchInput, TableFilterSelect, TableSortHeader, TableSkeleton, TableEmpty, TableError, TableBulkBar) · Dialog · Dock · DropdownMenu · Empty · EntitySelector · Field · Form · HeroAction · HoverCard · IconPicker · ImagePicker · Input · InputGroup · InputOTP · Item · Kbd · Label · Logo · MediaTile · NumberField · OptionCard · Overlay · PageHeader · Pagination · PasswordInput · PickerSearch · Popover · Progress · RadioGroup · Resizable · ResponsiveDialog · SchemaForm · ScopeIndicator · ScrollArea · SectionCard · Select · SelectionScope (SelectionHighlight) · Separator · SettingsRow (SwitchRow, LabeledField, LabeledInput, LabeledIconPicker, RowActions, SectionAddButton, SectionEmpty) · Sheet · Skeleton · Slider · SlidingIndicator (deprecated) · Sonner (toast) · Spinner · StepIndicator · Switch · Table · Tabs · Textarea · TierBadge · Toggle · ToggleGroup · Tooltip · WidgetCard · WidgetIdentity · WidgetTrustBadge

Badge is glass-only: tone takes any CSS color (<Badge tone="var(--success)">); there are no solid variant badges.

@glasshome/ui/tokens — design tokens as data

Framework-free theme model: presets, oklch parsing/derivation, and oklch→hex conversion (gamut-mapped, for renderers that cannot parse oklch). Safe in Node scripts, servers, and build tooling.

import { THEME_PRESETS, DEFAULT_THEME_ID, resolveThemeColors, oklchToHex } from "@glasshome/ui/tokens";

Astro

.astro files import @glasshome/ui/solid like any Solid file. The package ships its source under the solid export condition, so Astro's Solid integration compiles it for the server; a component with no client: directive renders to static HTML with no runtime shipped.

@glasshome/ui/styles — Tailwind v4 CSS

@import "@glasshome/ui/styles";

Provides the glass material, design tokens (colors, radii, animations), and the Tailwind v4 theme layer. @glasshome/ui/styles/theme exposes the token palette alone.

Development

bun install
bun run dev:gallery   # live component gallery on :5199, hot-reloads against src
bun run test          # vitest unit + render smoke tests
bun run lint          # biome
bun run check:tokens  # theme.css <-> tokens/presets.ts sync guard
bun run check:types   # typecheck src + tests
bun run build         # dist ESM + declarations
bun run check:publish # publint + arethetypeswrong

License

MIT

版本与发布记录

@glasshome/ui 共发布 84 个版本,首次发布于 2026/03/23;过去 12 个月发布了 84 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
1.40.0latest2026/11/16今天
1.39.02026/11/079 天前
1.38.02026/11/079 天前
1.37.22026/11/0610 天前
1.37.12026/11/0610 天前
1.37.02026/11/0610 天前

关于 @glasshome/ui 的常见问题

@glasshome/ui 是什么?

SolidJS component library for GlassHome, built on Kobalte

如何安装 @glasshome/ui?

在项目目录运行 npm install @glasshome/ui,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:solid-js(^1.9.9)、tailwindcss(^4.1.13)、tw-animate-css(^1.4.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@glasshome/ui 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@glasshome/ui 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@glasshome/ui 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=20。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@glasshome/ui 可以商用吗?

@glasshome/ui 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@glasshome/ui 的下载量有多少?

根据 npm 官方下载统计,@glasshome/ui 在 2026/10/17 – 2026/11/15 这 30 天内被下载 3,377 次,日均约 113 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@glasshome/ui 还在维护吗?

最新版本 1.40.0 发布于 2026/11/16(今天);至今共发布 84 个版本,其中过去 12 个月发布了 84 个;首次发布于 2026/03/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。