@duskmoon-dev/core

中文文档

1.21.5发布于 2026/11/12MITTypeScriptESM + CJS零依赖构建来源已验证近 30 天下载 3.9万

DuskMoonUI - Tailwind CSS v4 plugin with Material Design 3 color system and component styles

文档目录41 节

Features
Installation
Native Overlay Principles
Quick Start
1. Add DuskMoonUI to your CSS
2. Add the theme attribute to your HTML
3. Use the color utilities
Theme Switching
Components
Core Components (6)
Data Display (5)
Data Entry (6)
Feedback (7)
Layout (2)
Navigation (5)
Surfaces (4)
Misc (1)
Component Examples
Button
Card
Avatar
Alert
Progress
Toast
Stepper
Color System
Brand Colors (12 tokens)
Surface Colors (10 tokens)
Semantic Colors (12 tokens)
Neutral Colors (10 tokens)
Outline Colors (2 tokens)
Custom Themes
OKLCH Color Values
Accessibility
Requirements
Development
Migration from v1.x
Color Format Change
Removed Tokens
Transparency
License

@duskmoon-dev/core

DuskMoonUI - A Tailwind CSS v4 plugin with Material Design 3 color system and 49 component styles

Features

🎨 Three-color system - Primary, secondary, and tertiary brand colors with automatic content colors
🌓 Built-in themes - Sunshine (light) and Moonlight (dark) themes ready to use
📦 55+ Material Design 3 color tokens - Full MD3 color system with OKLCH format
🧩 49 UI components - Complete component library with consistent styling
🚀 Zero runtime JS - Pure CSS with CSS custom properties for theme switching
♿ Accessible by default - WCAG AA compliant contrast ratios (4.5:1 minimum)
🎯 Tailwind v4 native - Pure CSS using @import, no JavaScript configuration
📦 Tiny bundle - Under 7KB gzipped

Installation

# Using Bun (recommended)
bun add @duskmoon-dev/core tailwindcss@^4.0.0

# Using npm
npm install @duskmoon-dev/core tailwindcss@^4.0.0

# Using pnpm
pnpm add @duskmoon-dev/core tailwindcss@^4.0.0

Native Overlay Principles

Tooltips use only the HTML Popover API: popover="hint", interestfor, and browser-owned :popover-open state.
Modal and Dialog use only HTML <dialog>, opened with command="show-modal" / commandfor or showModal(), and closed with native commands, close(), or method="dialog". The browser manages the backdrop, inertness, keyboard focus, and Escape.

Legacy div-based Modal markup, .modal-open, .modal-toggle, and URL-target visibility are no longer supported. Migrate the outer element to <dialog> and use native opening/closing actions; .modal-box and presentation modifiers remain available.

Quick Start

1. Add DuskMoonUI to your CSS

Option A: CSS `@import` (recommended)

/* src/styles.css */
@import "tailwindcss";
@import "@duskmoon-dev/core";

Option B: Tailwind `@plugin` directive

/* src/styles.css */
@import "tailwindcss";
@plugin "@duskmoon-dev/core/plugin";

The @plugin approach registers Material Design 3 color tokens directly into Tailwind's theme, enabling utility classes like bg-primary, text-on-surface, etc. Use this when you need Tailwind-aware color utilities alongside the component styles.

2. Add the theme attribute to your HTML

<html data-theme="sunshine">
  <body>
    <button class="btn btn-primary">Click me</button>
  </body>
</html>

3. Use the color utilities

<!-- Brand colors -->
<div class="bg-primary text-primary-content">Primary</div>
<div class="bg-secondary text-secondary-content">Secondary</div>
<div class="bg-tertiary text-tertiary-content">Tertiary</div>

<!-- Surface colors -->
<div class="bg-surface text-on-surface">Surface</div>
<div class="bg-surface-container">Container</div>

<!-- Semantic colors -->
<div class="bg-success text-success-content">Success</div>
<div class="bg-error text-error-content">Error</div>

Theme Switching

Switch themes by changing the data-theme attribute - no JavaScript required:

<!-- Light theme -->
<html data-theme="sunshine">

<!-- Dark theme -->
<html data-theme="moonlight">

Theme switching is instant and uses pure CSS custom properties.

Components

@duskmoon-dev/core includes 50+ components organized by category:

Core Components (6)

Component	Classes	Description
Button	`.btn`, `.btn-primary`, `.btn-secondary`, `.btn-outline`, `.btn-ghost`	Buttons with variants, sizes, and states
Card	`.card`, `.card-body`, `.card-title`, `.card-bordered`	Content containers with headers and actions
Input	`.input`, `.input-bordered`, `.input-primary`	Text inputs with sizes and states
Form	`.form-control`, `.label`, `.checkbox`, `.radio`, `.toggle`, `.select`, `.textarea`	Form elements and layouts
Navigation	`.navbar`, `.megamenu`, `.menu`, `.link`, `.breadcrumbs`, `.tabs`, `.pagination`, `.dropdown`	Navigation patterns
Modal	`dialog.modal`, `.modal-box`, `.modal-action`	Native HTML dialog overlays

Data Display (5)

Component	Classes	Description
Avatar	`.avatar`, `.avatar-sm`, `.avatar-lg`, `.avatar-group`	User avatars with sizes and groups
Badge	`.badge`, `.badge-primary`, `.badge-outline`, `.badge-dot`	Status indicators and labels
Chip	`.chip`, `.chip-primary`, `.chip-outlined`, `.chip-closeable`	Interactive tags
List	`.list`, `.list-item`, `.list-bordered`, `.list-hoverable`	Vertical item lists
Table	`.table`, `.table-zebra`, `.table-hover`, `.table-bordered`	Data tables

Data Entry (6)

Component	Classes	Description
Autocomplete	`.autocomplete`, `.autocomplete-dropdown`, `.autocomplete-option`	Searchable dropdowns
Datepicker	`.datepicker`, `.datepicker-dropdown`, `.datepicker-day`	Date selection
File Upload	`.file-upload`, `.file-upload-dropzone`, `.file-upload-item`	File uploads with drag-drop
Rating	`.rating`, `.rating-item`, `.rating-half`	Star ratings
Slider	`.slider`, `.slider-thumb`, `.slider-track`	Range inputs
Switch	`.switch`, `.switch-track`, `.switch-thumb`	Toggle switches

Feedback (7)

Component	Classes	Description
Alert	`.alert`, `.alert-info`, `.alert-success`, `.alert-warning`, `.alert-error`	Alert messages
Dialog	`.dialog`, `.dialog-header`, `.dialog-body`, `.dialog-footer`	Confirmation dialogs
Progress	`.progress`, `.progress-bar`, `.progress-circular`	Progress indicators
Skeleton	`.skeleton`, `.skeleton-text`, `.skeleton-circle`, `.skeleton-wave`	Loading placeholders
Snackbar	`.snackbar`, `.snackbar-message`, `.snackbar-action`	Brief notifications
Toast	`.toast`, `.toast-container`, `.toast-info`, `.toast-success`	Toast notifications
Tooltip	`.tooltip[popover]`, `.tooltip-top`, `.tooltip-bottom`	Hint popovers (`interestfor`)

Layout (2)

Component	Classes	Description
App Bar	`.appbar`, `.appbar-title`, `.appbar-nav`, `.appbar-actions`	Top app bars
Divider	`.divider`, `.divider-vertical`, `.divider-text`	Content separators

Component	Classes	Description
Bottom Navigation (Dock)	`.bottom-nav`, `.bottom-nav-item`, `.bottom-nav-indicator`	Mobile navigation
Drawer	`.drawer`, `.drawer-content`, `.drawer-nav-item`	Side navigation
Link	`.link`, `.link-hover`, `.link-primary`, `.link-neutral`	Native text links
Megamenu	`.megamenu`, `.megamenu-trigger`, `.megamenu-panel`, `.megamenu-grid`	Grouped site navigation
Stepper (Steps)	`.stepper`, `.stepper-step`, `.stepper-indicator`	Multi-step processes

Surfaces (4)

Component	Classes	Description
Accordion	`.accordion`, `.accordion-item`, `.accordion-header`, `.accordion-content`	Expandable panels
Bottom Sheet	`.bottomsheet`, `.bottomsheet-handle`, `.bottomsheet-content`	Mobile sheets
Collapse	`.collapse`, `.collapse-content`, `.collapse-toggle`	Collapsible content
Popover	`.popover[popover]`, `.popover-body`, `.popover-arrow`	Floating content (Popover API)

Misc (1)

Component	Classes	Description
Timeline	`.timeline`, `.timeline-item`, `.timeline-marker`	Event timelines

Component Examples

Button

<button class="btn">Default</button>
<button class="btn btn-primary">Primary</button>
<button class="btn btn-secondary">Secondary</button>
<button class="btn btn-tertiary">Tertiary</button>
<button class="btn btn-outline">Outline</button>
<button class="btn btn-ghost">Ghost</button>

<!-- Sizes -->
<button class="btn btn-xs">Extra small</button>
<button class="btn btn-sm">Small</button>
<button class="btn btn-lg">Large</button>

Card

<div class="card">
  <div class="card-body">
    <h2 class="card-title">Card title</h2>
    <p>Card content goes here.</p>
    <div class="card-actions">
      <button class="btn btn-primary">Action</button>
    </div>
  </div>
</div>

Avatar

<div class="avatar">
  <img src="user.jpg" alt="User" />
</div>
<div class="avatar avatar-lg avatar-rounded">
  <img src="user.jpg" alt="User" />
</div>
<div class="avatar-group">
  <div class="avatar"><img src="user1.jpg" /></div>
  <div class="avatar"><img src="user2.jpg" /></div>
  <div class="avatar"><img src="user3.jpg" /></div>
</div>

Alert

<div class="alert alert-info">
  <span class="alert-icon">ℹ</span>
  <span class="alert-message">Information message</span>
</div>
<div class="alert alert-success">Success!</div>
<div class="alert alert-warning">Warning!</div>
<div class="alert alert-error">Error!</div>

Progress

<!-- Linear -->
<div class="progress">
  <div class="progress-bar" style="width: 60%"></div>
</div>

<!-- Indeterminate -->
<div class="progress progress-indeterminate">
  <div class="progress-bar"></div>
</div>

<!-- Circular -->
<div class="progress-circular">
  <svg><circle class="progress-circular-track" /><circle class="progress-circular-bar" /></svg>
</div>

Toast

<div class="toast-container toast-container-top-right">
  <div class="toast toast-success show">
    <span class="toast-icon">✓</span>
    <div class="toast-content">
      <span class="toast-title">Success</span>
      <span class="toast-message">Your changes have been saved.</span>
    </div>
    <button class="toast-close">×</button>
  </div>
</div>

Stepper

<div class="stepper">
  <div class="stepper-step completed">
    <div class="stepper-indicator">1</div>
    <span class="stepper-title">Step 1</span>
  </div>
  <div class="stepper-step active">
    <div class="stepper-indicator">2</div>
    <span class="stepper-title">Step 2</span>
  </div>
  <div class="stepper-step">
    <div class="stepper-indicator">3</div>
    <span class="stepper-title">Step 3</span>
  </div>
</div>

Color System

DuskMoonUI v2.0 uses the OKLCH color format for perceptually uniform color manipulation.

Brand Colors (12 tokens)

Use on-primary-container, on-secondary-container, and on-tertiary-container for colored text on surfaces. Bright role colors are fills: pair primary with primary-content, for example. The same foreground rule applies to semantic roles. Components keep these uses separate so outlined/text controls remain readable without changing the theme palette. For accent text, use light-dark(var(--color-accent-content), var(--color-accent)) with the theme's color-scheme.

primary, primary-content, primary-container, on-primary-container
secondary, secondary-content, secondary-container, on-secondary-container
tertiary, tertiary-content, tertiary-container, on-tertiary-container

Note: -focus tokens are removed in v2.0. Use color-mix() instead:
.btn:hover {
  background-color: color-mix(in oklch, var(--color-primary), black 10%);
}

Surface Colors (10 tokens)

surface, surface-dim, surface-bright
surface-container-lowest, surface-container-low, surface-container, surface-container-high, surface-container-highest
on-surface, on-surface-variant

Semantic Colors (12 tokens)

info, info-content, info-container, on-info-container
success, success-content, success-container, on-success-container
warning, warning-content, warning-container, on-warning-container
error, error-content, error-container, on-error-container

Neutral Colors (10 tokens)

base-100 through base-900
base-content

Outline Colors (2 tokens)

outline, outline-variant

Custom Themes

Define custom themes using OKLCH format:

[data-theme="custom"] {
  color-scheme: light;

  /* OKLCH format: oklch(L% C H) */
  /* L = Lightness (0-100%), C = Chroma (0-0.4), H = Hue (0-360) */
  --color-primary: oklch(65% 0.18 255);
  --color-primary-content: oklch(100% 0 0);
  --color-secondary: oklch(60% 0.18 300);
  --color-secondary-content: oklch(100% 0 0);
  --color-tertiary: oklch(70% 0.15 80);
  --color-tertiary-content: oklch(20% 0 0);

  /* Base colors */
  --color-base-100: oklch(100% 0 0);
  --color-base-200: oklch(98% 0.01 85);
  --color-base-300: oklch(96% 0.01 85);
  --color-base-content: oklch(27% 0.02 260);

  /* Add remaining tokens... */
}

OKLCH Color Values

Hue	Color
0/360	Pink
30	Red
55	Orange
80	Yellow
145	Green
185	Teal
235	Blue
255	Indigo
300	Purple

Accessibility

All components include:

Keyboard navigation - Full keyboard support with focus indicators
Screen reader support - Proper ARIA attributes and semantic HTML
Color contrast - WCAG AA compliant (4.5:1 minimum)
Reduced motion - Respects prefers-reduced-motion preference

Requirements

Tailwind CSS v4.0.0 or later
Modern browsers with OKLCH and color-mix() support:
- Chrome 111+ (March 2023)
- Safari 15.4+ (March 2022)
- Firefox 113+ (May 2023)
- Edge 111+ (March 2023)
Global browser support: ~92%

Development

# Install dependencies
bun install

# Build the package
bun run build

# Watch mode
bun run dev

# Type check
bun run typecheck

# Run tests
bun run test
bun run test:visual
bun run test:integration
bun run test:a11y

Migration from v1.x

v2.0.0 introduces OKLCH color format (breaking change):

Color Format Change

Before (v1.x - HSL):

/* Theme values stored as HSL components */
--color-primary: 30 90% 55%;
background-color: hsl(var(--color-primary));

After (v2.0 - OKLCH):

/* Theme values stored as full OKLCH */
--color-primary: oklch(72% 0.18 55);
background-color: var(--color-primary);

Removed Tokens

The -focus tokens are removed. Use color-mix() instead:

/* Before */
background-color: hsl(var(--color-primary-focus));

/* After */
background-color: color-mix(in oklch, var(--color-primary), black 10%);

Transparency

/* Before */
background-color: rgba(var(--color-primary-rgb), 0.5);

/* After */
background-color: color-mix(in oklch, var(--color-primary) 50%, transparent);

See specs/004-oklch-color-system/quickstart.md for detailed migration guide.

License

MIT

版本与发布记录

@duskmoon-dev/core 共发布 68 个版本，首次发布于 2025/10/26；过去 12 个月发布了 67 个版本。最新版本附带 npm provenance 构建来源证明，可追溯到公开的 CI 构建记录。

版本	发布日期	距今
`1.21.5`latest	2026/11/12	1 天前
`1.21.4`	2026/11/11	2 天前
`1.21.3`	2026/11/11	2 天前
`1.21.2`	2026/11/08	5 天前
`1.21.1`	2026/11/07	6 天前
`1.21.0`	2026/11/05	8 天前

关于 @duskmoon-dev/core 的常见问题

@duskmoon-dev/core 是什么？

DuskMoonUI - Tailwind CSS v4 plugin with Material Design 3 color system and component styles

如何安装 @duskmoon-dev/core？

在项目目录运行 npm install @duskmoon-dev/core，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：tailwindcss（^4.0.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

@duskmoon-dev/core 支持 TypeScript 吗？

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

@duskmoon-dev/core 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require() 都可以使用，打包工具会自动选择合适的版本。

@duskmoon-dev/core 需要什么版本的 Node.js？

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

@duskmoon-dev/core 可以商用吗？

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

@duskmoon-dev/core 的下载量有多少？

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

@duskmoon-dev/core 还在维护吗？

最新版本 1.21.5 发布于 2026/11/12（1 天前）；至今共发布 68 个版本，其中过去 12 个月发布了 67 个；首次发布于 2025/10/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

npm install @duskmoon-dev/core

pnpmpnpm add @duskmoon-dev/core
yarnyarn add @duskmoon-dev/core
bunbun add @duskmoon-dev/core

peer 依赖tailwindcss ^4.0.0

npm 7+ 与 pnpm 8+ 会自动安装必需的 peer 依赖，Yarn 需手动安装。

在你的项目目录中运行此命令。

近 30 天下载

38,922

约 3.9万次日均 1,297 次

统计周期 2026/10/13 – 2026/11/11
数据来自 npm 官方下载统计，今天更新

最新版本1.21.5发布于 1 天前

开源许可MIT宽松许可

包体积5.7 MB295 个文件 · 解压后

运行依赖0 个另有 1 个 peer 依赖

模块格式ESM + CJS

TypeScript自带类型

Node.js>=18.0.0

发布版本68 个近 12 个月 67 个

首次发布2025/10/261 年前

元数据更新2026/11/12

每一个软件包背后，
都有分享与创造的人。

@duskmoon-dev/core

@duskmoon-dev/core

Features

Installation

Native Overlay Principles

Quick Start

1. Add DuskMoonUI to your CSS

Option A: CSS @import (recommended)

Option B: Tailwind @plugin directive

2. Add the theme attribute to your HTML

3. Use the color utilities

Theme Switching

Components

Core Components (6)

Data Display (5)

Data Entry (6)

Feedback (7)

Layout (2)

Navigation (5)

Surfaces (4)

Misc (1)

Component Examples

Button

Card

Avatar

Alert

Progress

Toast

Stepper

Color System

Brand Colors (12 tokens)

Surface Colors (10 tokens)

Semantic Colors (12 tokens)

Neutral Colors (10 tokens)

Outline Colors (2 tokens)

Custom Themes

OKLCH Color Values

Accessibility

Requirements

Development

Migration from v1.x

Color Format Change

Removed Tokens

Transparency

License

版本与发布记录

关于 @duskmoon-dev/core 的常见问题

@duskmoon-dev/core 是什么？

如何安装 @duskmoon-dev/core？

@duskmoon-dev/core 支持 TypeScript 吗？

@duskmoon-dev/core 支持 ESM 还是 CommonJS？

@duskmoon-dev/core 需要什么版本的 Node.js？

@duskmoon-dev/core 可以商用吗？

@duskmoon-dev/core 的下载量有多少？

@duskmoon-dev/core 还在维护吗？

Option A: CSS `@import` (recommended)

Option B: Tailwind `@plugin` directive