duskmoon-dev-core（黄昏之月开发核心）

@duskmoon-dev/core Skill

Overview

@duskmoon-dev/core is a CSS-only component library for Tailwind CSS v4 with Material Design 3's extended color system.

Installation

# Bun
bun add @duskmoon-dev/core tailwindcss@^4.0.0

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

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

Setup

Option A: CSS Import (Recommended)

@import "tailwindcss";
@import "@duskmoon-dev/core";

Option B: Tailwind Plugin

@import "tailwindcss";
@plugin "@duskmoon-dev/core/plugin";

The @plugin approach registers MD3 color tokens into Tailwind's theme, enabling utility classes like bg-primary, text-on-surface, etc.

Theme Configuration

Apply theme via data-theme attribute on HTML element:

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

Available Components

Actions

• btn - Buttons with variants: btn-primary, btn-secondary, btn-tertiary, btn-outline, btn-ghost, btn-text, btn-loading
• circle-menu - Radial navigation menu: circle-menu-toggler, circle-menu-list, circle-menu-item, circle-menu-label, circle-menu-primary, circle-menu-secondary, circle-menu-tertiary, circle-menu-info, circle-menu-success, circle-menu-warning, circle-menu-error, circle-menu-sm, circle-menu-lg
• file-upload - Drag-and-drop file uploader: file-upload-dropzone, file-upload-primary, file-upload-compact, file-upload-button, file-upload-sm, file-upload-lg, file-upload-ghost
• toggle-btn - Toggle buttons and groups: toggle-btn-active, toggle-btn-primary, toggle-btn-ghost, toggle-btn-sm, toggle-btn-lg, toggle-group, toggle-segmented, toggle-chip, toggle-filled, toggle-outlined

Data Entry

• input - Text inputs: input-primary, input-secondary, input-error
• textarea - Multi-line text: textarea-primary, textarea-resize-none, textarea-resize-vertical
• select - Dropdown selection: select-primary, select-filled, select-outlined
• cascader - Hierarchical selection: cascader, cascader-panel, cascader-menu
• checkbox - Checkboxes: checkbox-primary, checkbox-indeterminate, checkbox-group
• radio - Radio buttons: radio-primary, radio-group, radio-group-horizontal
• switch - Toggle switches: switch-primary, switch-secondary
• slider - Range sliders
• segment-control - Segmented buttons: segment-control, segment-control-item
• autocomplete - Search with suggestions
• datepicker - Calendar: date, datetime, date range, datetime range pickers
• time-input - Time selection: time-input, time-input-picker
• file-upload - Drag-and-drop file uploader
• rating - Star/heart ratings
• otp-input - OTP verification: otp-input, otp-input-field
• pin-input - PIN entry: pin-input, pin-input-masked
• multi-select - Multiple selection: multi-select, multi-select-tag
• tree-select - Hierarchical dropdown: tree-select, tree-select-node
• form-group - Form layout: form-group, form-label, helper-text, fieldset
• theme-controller - Theme switching: theme-controller (inline switch), theme-controller-dropdown, theme-controller-item, theme-controller-label

Data Display

• card - Content containers: card-body, card-title
• badge - Status indicators: badge-primary, badge-dot
• avatar - User images: avatar-lg, avatar-status-online
• chip - Tags/filters: chip-primary, chip-removable
• table - Data tables: table-hover, table-striped
• list - Vertical lists: list-item, list-item-interactive
• timeline - Chronological events
• skeleton - Loading placeholders: skeleton-text, skeleton-circle, skeleton-rect, skeleton-wave, skeleton-avatar, skeleton-button, skeleton-card, skeleton-group
• code-block - Styled code containers: code-header, code-title, code-language, code-content, code-block-compact, code-block-borderless

Feedback

• alert - Messages: alert-success, alert-error, alert-warning, alert-info
• dialog - Modal dialogs: dialog-backdrop, dialog-md
• modal - Full overlays
• toast - Notifications: toast-success, toast-show
• snackbar - Brief messages
• progress - Loading: progress-primary, progress-indeterminate
• skeleton - Placeholders: skeleton-text, skeleton-circle
• tooltip - Hover info: tooltip-top, tooltip-bottom

Navigation

• breadcrumbs - Breadcrumb navigation: breadcrumb-item, breadcrumb-item-active, breadcrumb-item-disabled, breadcrumb-link, breadcrumb-separator, breadcrumb-icon, breadcrumb-home, breadcrumb-home-icon, breadcrumb-ellipsis, breadcrumbs-contained, breadcrumbs-sm, breadcrumbs-lg, breadcrumbs-nowrap
• navbar - Top navigation: navbar-surface-container-high, navbar-start, navbar-center, navbar-end
• tabs - Tab navigation: tab, tab-active, tabs-boxed, tabs-lifted, tab-sm, tab-lg, tab-xs
• menu - Dropdown/context menu: menu-item, menu-title, menu-horizontal, menu-vertical
• drawer - Side panels: drawer-left, drawer-open
• nested-menu - Collapsible sidebar: nested-menu, nested-menu-title, nested-menu-bordered, nested-menu-compact
• pagination - Page navigation: pagination-item, pagination-item-active, pagination-item-disabled, pagination-prev, pagination-next, pagination-ellipsis, pagination-compact, pagination-responsive, pagination-info, pagination-input, pagination-item-active-primary, pagination-item-active-secondary, pagination-item-active-tertiary
• bottom-nav - Mobile navigation: bottom-nav-item
• stepper - Multi-step: stepper-step-active, stepper-step-completed

Layout

• divider - Separators: divider-dashed, divider-vertical
• appbar - Action bars: appbar-top, appbar-bottom
• markdown-body - GitHub-style markdown typography: single class applied to a container, styles all child elements (headings, code, tables, blockquotes, lists)
• grid-cols-auto-fill-* - Responsive grid with auto-fill: grid-cols-auto-fill-48, grid-cols-auto-fill-64
• grid-cols-auto-fit-* - Responsive grid with auto-fit: grid-cols-auto-fit-48, grid-cols-auto-fit-64

Utilities

• sr-only - Screen reader only (visually hidden but accessible)
• not-sr-only - Undo sr-only for focus states

Surfaces

• accordion - Expandable panels: accordion-item-open
• bottomsheet - Mobile panels: bottom-sheet-show
• popover - Contextual overlays: popover-top, popover-show
• collapse - Collapsible content

Usage Examples

Buttons

<button class="btn btn-primary">Primary</button>
<button class="btn btn-secondary btn-outline">Outlined</button>
<button class="btn btn-tertiary btn-ghost">Ghost</button>
<button class="btn btn-primary btn-loading">Loading...</button>

Cards

<div class="card">
  <div class="card-body">
    <h2 class="card-title">Title</h2>
    <p>Content</p>
  </div>
</div>

Forms

<input type="text" class="input" placeholder="Default" />
<input type="text" class="input input-primary" placeholder="Primary" />
<input type="text" class="input input-error" placeholder="Error" />

Alerts

<div class="alert alert-success">Success message</div>
<div class="alert alert-error">Error message</div>
<div class="alert alert-warning">Warning message</div>
<div class="alert alert-info">Info message</div>

Navigation

<nav class="navbar navbar-surface-container-high">
  <div class="navbar-start">
    <a class="navbar-brand">Logo</a>
  </div>
  <div class="navbar-center">
    <a class="navbar-item navbar-item-active">Home</a>
    <a class="navbar-item">About</a>
  </div>
</nav>

Tabs

<div class="tabs">
  <button class="tab tab-active">Tab 1</button>
  <button class="tab">Tab 2</button>
</div>

Dialog

<div class="dialog-backdrop dialog-backdrop-show">
  <div class="dialog dialog-md">
    <div class="dialog-header">
      <h2 class="dialog-title">Title</h2>
    </div>
    <div class="dialog-body">Content</div>
    <div class="dialog-actions">
      <button class="btn btn-text">Cancel</button>
      <button class="btn btn-filled">Confirm</button>
    </div>
  </div>
</div>

Nested Menu

<ul class="nested-menu nested-menu-bordered">
  <li class="nested-menu-title">Getting Started</li>
  <li><a href="/install">Installation</a></li>
  <li><a href="/config" class="active">Configuration</a></li>
  <li>
    <details open>
      <summary>Components</summary>
      <ul>
        <li><a href="/button">Button</a></li>
        <li><a href="/card">Card</a></li>
      </ul>
    </details>
  </li>
</ul>

Theme Controller

<!-- Inline switch mode -->
<div class="theme-controller">
  <input type="radio" name="theme" value="sunshine" class="theme-controller-item" checked />
  <label class="theme-controller-label">Light</label>
  <input type="radio" name="theme" value="moonlight" class="theme-controller-item" />
  <label class="theme-controller-label">Dark</label>
</div>

<!-- Dropdown mode -->
<details class="theme-controller-dropdown">
  <summary class="theme-controller-trigger">Theme</summary>
  <div class="theme-controller-menu">
    <input type="radio" name="theme" value="sunshine" class="theme-controller-item" checked />
    <label class="theme-controller-label">Sunshine</label>
    <input type="radio" name="theme" value="moonlight" class="theme-controller-item" />
    <label class="theme-controller-label">Moonlight</label>
  </div>
</details>

Toggle Buttons

<!-- Single toggle -->
<button class="toggle-btn toggle-btn-active">Bold</button>

<!-- Toggle group -->
<div class="toggle-group">
  <button class="toggle-btn toggle-btn-active">Left</button>
  <button class="toggle-btn">Center</button>
  <button class="toggle-btn">Right</button>
</div>

Responsive Grid

<!-- Auto-fill: Fixed column size, empty space on right -->
<div class="grid grid-cols-auto-fill-48 gap-4">
  <div class="card">Item 1</div>
  <div class="card">Item 2</div>
  <div class="card">Item 3</div>
</div>

<!-- Auto-fit: Columns stretch to fill container -->
<div class="grid grid-cols-auto-fit-64 gap-4">
  <div class="card">Item 1</div>
  <div class="card">Item 2</div>
</div>

Color System

Color Utilities

<!-- Backgrounds -->
<div class="bg-primary">Primary</div>
<div class="bg-secondary">Secondary</div>
<div class="bg-tertiary">Tertiary</div>
<div class="bg-surface-container">Surface</div>

<!-- Text -->
<p class="text-primary">Primary</p>
<p class="text-on-surface">On surface</p>
<p class="text-on-surface-variant">Muted</p>

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

CSS Variables

.custom {
  background-color: var(--color-primary);
  color: var(--color-primary-content);
  border-color: var(--color-outline);
}

Theme Switching

// Switch to dark theme
document.documentElement.dataset.theme = 'moonlight';

// Switch to light theme
document.documentElement.dataset.theme = 'sunshine';

Importing Component Styles

Full Library Import

Import all components and themes at once:

/* In your CSS file */
@import "tailwindcss";
@import "@duskmoon-dev/core";

Individual Component CSS Import

Import only the CSS you need for smaller bundle sizes:

/* CSS imports */
@import "@duskmoon-dev/core/components/button";
@import "@duskmoon-dev/core/components/card";
@import "@duskmoon-dev/core/components/input";
@import "@duskmoon-dev/core/components/alert";

JavaScript/TypeScript Import

// Import component styles in JS/TS
import '@duskmoon-dev/core/components/button';
import '@duskmoon-dev/core/components/card';
import '@duskmoon-dev/core/components/input';

Theme-Only Import

/* Import specific themes */
@import "@duskmoon-dev/core/themes/sunshine";
@import "@duskmoon-dev/core/themes/moonlight";

Available Component Exports

All components available for individual import:

Usage in Web Components / Custom Elements

Each component exports a named css export containing the CSS string:

// Import the css named export
import { css as buttonCSS } from '@duskmoon-dev/core/components/button';
import { css as cardCSS } from '@duskmoon-dev/core/components/card';
import { css as inputCSS } from '@duskmoon-dev/core/components/input';

Example usage in a custom element:

import { css as buttonCSS } from '@duskmoon-dev/core/components/button';

// Strip @layer wrapper for Shadow DOM compatibility
const coreStyles = buttonCSS.replace(/@layer\s+components\s*\{/, '').replace(/\}\s*$/, '');

class MyButton extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });

    // Add styles to shadow DOM
    const style = document.createElement('style');
    style.textContent = coreStyles;
    this.shadowRoot.appendChild(style);
  }
}

Note: The CSS is wrapped in @layer components {} for Tailwind CSS cascade layers. When using in Shadow DOM, strip the @layer wrapper as shown above.