[Github] Looseleaf – 为 shadcn/ui 加上纸张与手绘笔触的 React 组件库

Github发现2026-11-04发布 WarpEdit

Looseleaf 是一套把 shadcn/ui 画成纸张与手绘笔触的 React 组件库：按钮有马克笔填色，卡片像便笺，标签、贴纸和图标也延续同一种画法。它面向 React 19、Tailwind CSS v4 和 Radix 项目，通过 shadcn registry 把组件源码加入你的代码库，适合想让笔记、学习工具或轻量产品带一点纸面质感的开发者。

Looseleaf 手绘 React 组件库概念封面：源码连接纸面按钮、输入框和便笺区块

手绘感从哪里来

纸面有纹理，轮廓会表现笔触，主要按钮用实色填充，次要按钮像荧光笔划过的纸片，链接则带手写下划线。Kevin Sans 手写字体又按界面文字、标题和印章三种用途安排，让控件与内容看起来出自同一本笔记。

Looseleaf 官方 Button 演示中的实色、删除、轮廓、次要、幽灵和链接六种按钮变体 — 官方 Button 演示：同一组按钮用填色、轮廓和下划线区分不同用途。

这些外观下面仍是实际 DOM 控件。绘图层使用 SVG，文字标签保留为真实文本；绘图函数由种子值决定，同一个种子在服务端和浏览器里得到同样的线条。悬停、按下和聚焦状态通过 CSS 切换预先绘好的图层。

项目保留 shadcn/ui 的部件、props 和 data-slot 名称，也为键盘操作、焦点提示、减少动态效果和高对比度模式提供了适配。它把手绘当作表现层，控件仍沿用常规交互语义；具体页面改造后的可用性，还要结合自己的内容和布局检查。

从按钮到便笺界面

当前仓库列出 123 个组件和 61 个组合区块。日常 UI 部件之外，还有纸张、索引卡、胶带、印章、涂鸦、贴纸、绘图板和聊天输入框。它的用途可以很小：给一个空状态加贴纸、把提示做成便笺；也可以从完整区块开始拼页面。

例如 Notes app 区块把笔记本做成侧边分类，把页面摘要做成一叠索引卡，编辑页则使用带标记工具的横线纸。下面是官方演示中的笔记列表，搜索框、分类、标题和摘要都沿用纸张视觉。

Looseleaf Notes app 官方预览，展示笔记分类、搜索框和横线纸索引卡列表 — 官方 Notes app 区块预览：纸张卡片承担真实的信息分组和阅读层级。

区块提供的是前端界面和示例交互。拿 Notes app 做自己的产品时，账号、数据持久化和同步等业务部分需要另接。登录、仪表盘、定价和聊天区块同样适合用作布局起点，数据与服务需要自己接入。

接入现有项目

先确认项目具备 React 19、Tailwind CSS v4、shadcn CLI 4.x，以及 @/* 路径别名。已有 shadcn 项目可以继续使用现有配置；新项目先完成 npx shadcn@latest init。Vite 项目需要同时配置 TypeScript 与打包器别名，Next.js 的 App Router 则要把 Provider 放在客户端组件中。

在现有 components.json 中合并这一条 registry 配置，保留其他字段：

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

接着添加一个按钮作为最小尝试：

npx shadcn@latest add @looseleaf/button

CLI 会把按钮、绘图配方及相关依赖加入项目。组件以源码形式落在 components/ui/、lib/ink/ 等目录，你可以直接修改。随后在演示入口使用它：

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

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

在 Next.js 中，这段演示要放入带 "use client" 的组件文件。跑起项目后，应能看到带手绘轮廓的按钮；若一直只有普通边框，先检查 InkProvider、路径别名和主题 CSS 是否加载。出现字体不对的情况，再检查主题及字体配置。

按需安装与整套主题的影响不同。安装单个组件会保留已有颜色令牌，并补充缺少的 Looseleaf 令牌。npx shadcn@latest add @looseleaf/looseleaf 会安装主题、字体、绘图引擎与全部组件，同时将配色替换为 Notebook 调色板，CLI 会先询问。已有品牌色的项目更适合先试单个组件，并查看生成文件和样式改动。

需要完整布局时，可继续添加 npx shadcn@latest add @looseleaf/login-01。这类区块及其依赖会放入项目源码，区块目录为 components/blocks/，后续表单逻辑和接口由项目自己维护。