kevintngo/looseleaf

项目介绍

Looseleaf 是一个手绘纸张风格的 React 组件库，基于 Tailwind v4 和 Radix 构建。它保留了 shadcn/ui 的组件结构、props 和 data-slot 命名，因此通常可以直接替换现有 JSX 中的组件，而不必调整页面结构。手绘只是视觉装饰，底层语义仍是标准的 Radix。

项目包含 123 个组件、61 个区块（侧边栏、登录、注册、仪表盘、设置、定价、聊天、笔记和落地页）以及 160 个图标、48 个涂鸦、88 个贴纸、徽章和印章，还附带一套名为 Kevin Sans 的手写字体。可访问性方面包括键盘操作、可见焦点、AA 文本、24 px 点击目标、减少动态效果、强制颜色、RTL 和三种密度。

安装与使用

先在 components.json 中注册一次：

{
  "registries": { "@looseleaf": "https://kevintngo.github.io/looseleaf/r/{name}.json" }
}

然后用 shadcn CLI 按需添加：

npx shadcn@latest add @looseleaf/button
npx shadcn@latest add @looseleaf/login-01
npx shadcn@latest add @looseleaf/looseleaf

组件会以源码形式落到 components/ui/*.tsx 和 lib/ink/*，成为项目代码的一部分，而不是运行时依赖。总包 looseleaf 应会带入主题和 Kevin Sans；如果要手动加载字体，可以引入发布好的 CSS：

@import url("https://kevintngo.github.io/looseleaf/fonts/kevin-sans.css");

用 InkProvider 包裹应用后，像普通组件一样使用即可：

import { InkProvider } from "@/lib/ink/react"
import { Button } from "@/components/ui/button"

export function App() {
  return (
    <InkProvider>
      <Button>Save changes</Button>
    </InkProvider>
  )
}

在线文档站是 kevintngo.github.io/looseleaf；注册表格式可参考 shadcn 官方说明。

绘制机制

每个手绘元素都是一个位于真实 DOM 标签之后的 <svg data-ink>。线条由 src/lib/ink/recipes/<component>-ink.ts 中的纯函数配合种子生成，SVG 颜色来自 CSS 变量，因此相同种子在服务端和浏览器中画出同一条线。悬停、按下和焦点状态由 CSS 控制，通过显示预先画好的图层实现，不依赖 React 状态。颜色、笔宽和密度都暴露为 --ll-* token，并映射到 shadcn 的语义变量，这是定制外观的主要入口。

使用约束

• 面向 React、Tailwind v4 和 shadcn CLI，安装流程默认项目已有 shadcn 风格的 components.json。
• 组件以源码复制进仓库，需要由使用方自行维护这些生成文件。
• 代码、美术资源和 Kevin Sans 采用 MIT 许可证；IBM Plex Mono 采用 SIL OFL 1.1。

本地开发

如果要修改组件库或文档站：

npm install
npm run dev              # 文档站
npm run build            # 构建静态站点到 dist/
npm test                 # vitest
npm run registry:build   # 生成 registry.json 和 public/r/*.json

修改组件后需要运行 npm run registry:build，否则注册表仍提供旧源码。推送到 main 会把站点部署到 GitHub Pages。

HotRepo 点评

Looseleaf 在 HotRepo 2026-11-03 的 TypeScript 新项目榜上有记录，当时共 107 星，统计窗口内新增 5 星；2026-11-02 到 2026-11-03 的 UTC 观测中，累计星数从 102 升到 107。序列很短、样本也小，只能说明出现早期关注，不能据此判断长期趋势。它真正的区分点在分发方式：组件以普通源码交给使用方，语义仍是 Radix，因此团队可以先在文档站评估视觉可读性和可访问性，再决定是否采用这套外观。