usuzumi

v2.2.1

Published

4 days ago

Drop-in CSS and JavaScript components for personal sites, docs, and product pages.

0High
0Medium
0Low

mashiro0619

ui css usuzumi design-system components zero-build theme

Usuzumi

English | 更新日志

Usuzumi 是一套零构建 CSS 和 JavaScript UI 库，适合个人站点、应用介绍页、文档页面和小型产品工具。你可以直接在 HTML 中加载它，也可以从 npm 引入，或把生成后的 ui/ 文件放进自己的项目。

安装

npm install usuzumi

import "usuzumi/usuzumi.css";
import "usuzumi/usuzumi.js";

只有在使用 .uzu-signature 时，才需要额外引入签名字体：

import "usuzumi/usuzumi-signature.css";

CDN 用法：

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/usuzumi/ui/usuzumi.min.css">
<script src="https://cdn.jsdelivr.net/npm/usuzumi/ui/usuzumi.min.js" defer></script>

快速开始

当 Usuzumi 接管整个页面时，使用 uzu-root 和 uzu-app：

<html class="uzu-root" lang="zh-CN" data-theme="light">
  <body class="uzu-app">
    <main class="uzu-page">
      <section class="uzu-section">
        <div class="uzu-section-head">
          <p class="uzu-section-label">Overview</p>
          <h1 class="uzu-page-title">Project notes</h1>
        </div>
        <button class="uzu-button uzu-button-primary" type="button">Continue</button>
      </section>
    </main>
  </body>
</html>

如果只想在现有页面中局部使用，可以包一层 uzu-scope：

<section class="uzu-scope">
  <article class="uzu-card">
    <h3>Scoped component</h3>
    <p>This area adopts Usuzumi without taking over the whole page.</p>
  </article>
</section>

自定义

Usuzumi 通过已文档化的 --uzu-* CSS 自定义属性暴露样式接口，主样式表使用 @layer usuzumi 包裹，因此项目 CSS 可以在不提高选择器权重的情况下覆盖它。

:root {
  --uzu-radius-standard: 10px;
  --uzu-motion-base: 220ms;
}

.settings-panel {
  --uzu-card-block-gap: 16px;
  --uzu-field-gap: 8px;
}

完整变量列表和组件使用规则见 DESIGN.md。

文档

DESIGN.md：组件契约、设计规则、CSS 变量、运行时属性、事件和编写指引。
CHANGELOG.zh-CN.md：从 2.0.1 开始记录的正式发布更新日志。
THIRD_PARTY_NOTICES.md：内置第三方资源的许可说明。

运行时

usuzumi.js 无依赖，会在浏览器中自动初始化。它也可以安全地在 SSR 或 Node 环境中 import，动态插入内容后可手动初始化：

window.Usuzumi.init(container);
window.Usuzumi.destroy(container);

不需要语法高亮的页面可以使用 usuzumi-core.js。代码较多的页面可以再配合 usuzumi-highlight.js，并通过 data-uzu-code-highlight="visible" 将高亮延迟到代码块接近视口时执行。

运行时 data attribute 和自定义事件细节见 DESIGN.md。

包含内容

面向页面、章节、卡片、布局、表单、导航、反馈、浮层、数据视图、Markdown 编辑和状态界面的主题化 CSS 原语。
无框架、无运行时依赖的可选 JavaScript 交互。
热力图通过 data-uzu-heatmap 支持紧凑日期数据、可点击格子和内置事件详情。
Gallery 和 Image Viewer 支持渐进增强图片链接、JSON 或目录数据源，以及聚焦预览控件。
面向 npm 和 CDN 使用的生成版 CSS / JS bundle。
浏览器 API 和自定义事件的类型声明。
响应式顶部栏可通过 data-uzu-topbar-overflow 把溢出的导航链接折入公共“更多”菜单。
侧边导航区分普通应用侧栏 .uzu-sidebar-nav 和同页面板索引 .uzu-panel-index。
可选 core 与语法高亮运行时入口，用于降低轻量页面加载成本。

站点与示例

官网、组件目录、Markdown 编辑器页和更大的示例放在站点仓库中，避免文档专用需求进入 UI 库本体。

开发

npm run build
npm run validate

源文件在 ui/css/ 和 ui/js/。ui/ 中的公开入口，包括完整、core 和语法高亮 bundle，都是生成文件，请修改源文件后重新构建，不要手改。

npm run validate 会检查生成文件同步、源码约束、package exports、浏览器行为和组件页冒烟覆盖。

浏览器支持

Usuzumi 面向支持 CSS 自定义属性、color-mix()、:has() 和 :focus-visible 的现代浏览器。更旧的浏览器仍可使用，但部分视觉细节会退化。

许可

Usuzumi 代码使用 MIT License 发布。

内置的 Meddon 字体按其自身的 SIL Open Font License 条款再分发，详见 THIRD_PARTY_NOTICES.md。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Usuzumi

安装

快速开始

自定义

文档

运行时

包含内容

站点与示例

开发

浏览器支持

许可