Penpot 插件 UI 样式库 @penpot/plugin-styles 完全指南：主题令牌、组件样式与接入实践

Penpot 插件 UI 样式库 penpot/plugin-styles 完全指南主题令牌、组件样式与接入实践【免费下载链接】penpotPenpot: The open-source design platform for Product teams that need scalable collaboration.项目地址: https://gitcode.com/GitHub_Trending/pe/penpotPenpot 插件样式库penpot/plugin-styles是为 Penpot 插件生态提供的一套官方 CSS 基础样式包用于帮助插件开发者快速构建与 Penpot 主界面视觉风格一致的插件 UI。本文以 plugins/libs/plugins-styles/README.md 为主体骨架并结合仓库内该包的源码目录展开讲解读完你将掌握该样式包的安装方式、CSS 入口的组织结构、明暗主题与设计令牌体系以及按钮、输入框等组件样式的使用约定。一、包定位与使用前提Penpot 是一款开源的设计协作平台其插件通过 iframe 承载独立的 HTML 界面。为了让海量第三方插件在视觉上与宿主产品保持一致官方提供了penpot/plugin-styles这个纯 CSS 包它不包含任何 JavaScript 逻辑只提供一份帮助构建 Penpot 插件 UI 的 CSS 文件官方 README 原文描述。这意味着你既可以在原生 HTML/JS 中使用它也可以在 React、Vue 等任何前端工程中直接引入前提只是页面最终能加载 CSS 并遵循其约定的data-*属性与类名规范。需要特别说明的是该样式包与仓库中的插件运行时/类型库是相互独立的分层本仓库的插件体系还包含plugins/libs/plugins-runtime运行时 API、plugins/libs/plugin-types类型定义与plugins/libs/plugins-styles样式。plugins-styles只关心界面长得像 Penpot接入它不需要依赖其他 Penpot 插件包。二、安装与引入Getting Started官方 README 给出了两步最小接入流程本文在此基础上补充源码层面的说明。1. 安装npm install penpot/plugin-styles在当前仓库中该包由 plugins/libs/plugins-styles/package.json 定义包名为penpot/plugin-styles其 package.json 显示版本为1.5.0且不携带任何运行时依赖dependencies: {}因此安装成本极低。仓库使用 pnpm 管理依赖packageManager: pnpm11.20.0...如果你的工程同样使用 pnpm也可以等价地执行pnpm add penpot/plugin-styles。2. 引入 CSS在你项目的样式入口中导入打包产物import penpot/plugin-styles/styles.css;导入后该文件将把所有 core 与 component 层的规则聚合进你的产物。从源码实现看这一层汇总入口就是 styles.css它以import的方式顺序引入两个层次/*core*/ import url(core/generic.css); import url(core/swatches.css); import url(core/fonts.css); import url(core/spacing.css); /*components*/ import url(components/button.css); import url(components/checkbox.css); import url(components/radio-button.css); import url(components/icon.css); import url(components/select.css); import url(components/input.css); import url(components/switch.css);core 层负责地基全局重置、主题令牌、字体排版、间距标尺components 层负责构件按钮、勾选框、单选、图标、下拉选择、输入框、开关七类常见控件。三、源码目录结构core 与 components 的分层设计仓库内该包的源码真实布局如下与打包产物styles.css的引用一一对应plugins/libs/plugins-styles/src/lib/ ├── styles.css # 汇总入口被 penpot/plugin-styles/styles.css 暴露给使用者 ├── core/ │ ├── generic.css # 全局 reset、字体基线、滚动条 │ ├── swatches.css # 明暗主题的全部颜色设计令牌 │ ├── fonts.css # Work Sans 字体引入 排版工具类 │ └── spacing.css # 间距标尺令牌 ├── components/ │ ├── button.css # primary/secondary destructive 变体 │ ├── checkbox.css │ ├── radio-button.css │ ├── icon.css │ ├── select.css │ ├── input.css # 输入框与错误/成功态 │ └── switch.css └── icons/ └── chevron-bottom.svg # 包内自带的一个下拉箭头示例图标这种core components的物理拆分有两个直接收益其一打包时import顺序决定了层叠优先级core 的变量定义永远先于组件规则组件可以放心引用var(--…)令牌其二开发者阅读源码时能按关注点快速定位——想改颜色只看core/swatches.css想改按钮只看components/button.css。四、明暗双主题机制与颜色令牌体系Penpot 编辑器本身同时提供明light暗dark主题。plugin-styles把这一能力通过 HTML 根节点上的data-theme属性原样带给插件在html或包裹插件的根元素上设置data-themedark或data-themelight即可整体切换配色。4.1 主题如何映射令牌在 generic.css 中主题选择器只做令牌重映射而非直接写死颜色[data-themedark] { color-scheme: dark; --background-primary: var(--db-primary); --background-secondary: var(--db-secondary); --background-tertiary: var(--db-tertiary); --foreground-primary: var(--df-primary); --foreground-secondary: var(--df-secondary); --accent-primary: var(--da-primary); ... } [data-themelight] { color-scheme: light; --background-primary: var(--lb-primary); ... } [data-theme] { background-color: var(--background-primary); color: var(--foreground-secondary); }即语义令牌如--background-primary、--foreground-secondary、--accent-primary是一层稳定的接口而真正的颜色值--db-*/--lb-*等在 swatches.css 的:root中定义再按主题分别映射。这样业务代码永远引用语义变量切换主题时无需改动任何业务样式。同时color-scheme的声明会让原生表单控件如input、滚动条自动匹配系统深色渲染避免出现页面是深色、控件仍是白色的割裂感。4.2 颜色令牌速查来自 swatches.css 的实测值以下数值均可直接在 swatches.css 中核对令牌分组令牌名明色值暗色值语义说明背景 Background--db/lb-primary#ffffff#18181a页面主背景背景--db/lb-secondary#e8eaee#000000次级背景背景--db/lb-tertiary#f3f4f6#212426输入框/面板背景背景--db/lb-quaternary#eef0f2#2e3434hover 态背景前景 Foreground--df/lf-primary#000000#ffffff主文字前景--df/lf-secondary#495e74#8f9da3次级文字/占位符强调 Accent--da/la-primary#6911d4#7efff5主强调色强调--da/la-primary-muted#e1d2f5#426158强调弱化态强调--da/la-secondary#1345aa#bb97d8次强调色强调--da/la-tertiary#8c33eb#00d1b8hover/成功强调强调--da/la-quaternary#ff6fe0#ff6fe0第四强调色此外该文件还定义了与业务语义无关、跨主题保持一致的状态色与产品配色可直接用于表单校验与取色类场景状态色--success-50/500/950#f0f8ff/#2d9f8f/#0a2927、--warning-50/500/950、--error-50/200/500/700/950错误主色#ff3277深态#c80857、--info-50/500/950产品取色App Color--app-white、--app-black、--app-pink、--app-blue、--app-gold、--app-indigo、--app-red、--app-yellow、--app-purple、--app-lemon、--app-orange供需要展示色板选色的插件直接使用保证与 Penpot 内置取色器一致。五、排版与间距字体令牌与排版工具类5.1 Work Sans 与字号行高令牌fonts.css 通过 Bunny Fonts 引入 Penpot 界面同款字体 Work Sans仅加载 400/500 两个字重保证轻量并将html, body的字体族设定为Work Sans, sans-serif见 generic.css。同时暴露以下字体令牌字重--font-weight-regular: 400、--font-weight-bold: 500行高--font-line-height-s: 1.2、--font-line-height-m: 1.4、--font-line-height-l: 1.5字号--font-size-xs: 10px、--font-size-s: 12px、--font-size-m: 14px、--font-size-l: 16px需要留意的是import url(https://fonts.bunny.net/…)属于远程字体导入在离线或内容安全策略CSP严格的环境中插件若无法访问该域名将回退到sans-serif。可据此提前规划字体自托管方案。5.2 排版工具类fonts.css为文本层级提供了完整工具类无需为插件内每个标题手写字号类名字号行高特点.display36px1.2页面级大标题.title-l/.title-m/.title-s24px / 20px / 14px—分层级标题.headline-l/.headline-m/.headline-s18px / 16px / 12px—均text-transform: uppercase适合分区栏目标题headline-s加粗.body-l/.body-m/.body-s/.body-xs16px / 14px / 12px / 10px1.5 / 1.5 / 1.4 / 1.2正文层级.caption12px1.2说明文字.code-font以及code元素12px1.5等宽语境代码样式5.3 间距标尺spacing.css 以 4px 为基本单元构建间距标尺供 padding/margin/gap 统一使用:root { --spacing-4: 0.25rem; /* 4px */ --spacing-8: calc(var(--spacing-4) * 2); /* 8px */ --spacing-12: calc(var(--spacing-4) * 3);/* 12px */ /* …依次累乘直至 */ --spacing-40: calc(var(--spacing-4) * 10); /* 40px */ }实际覆盖--spacing-4到--spacing-40共 10 档。所有组件内部的圆角如按钮border-radius: 8px、输入框圆角var(--spacing-8)、内边距均复用这些令牌因此插件中新增的局部样式也建议统一引用var(--spacing-*)以保持整份 UI 的视觉节律一致。六、组件样式按钮与输入框的实战细节组件层覆盖按钮、勾选框、单选、图标、下拉选择、输入框、开关七类控件。其中按钮与输入框的实现最完整本文结合源码给出可直接照做的用法。6.1 按钮components/button.css按钮样式通过data-appearance属性而非额外类名区分主要/次要样式选择器为[data-appearance]:is(button)与[roletab]:is(button)后者意味着 tab 角色元素也可复用按钮观感并统一兜底了:disabled、:focus-visible等状态。基础外观由如下规则给出字号 12px、字重 500、圆角 8px、内边距8px 24px、全大写字母text-transform: uppercase文字默认透明 2px 边框。支持两种外观值与一种危险变体!-- 主要按钮用强调色填充用于主操作 -- button>label forname名称/label input classinput idname placeholder请输入… required / !-- 隐藏 label、仅保留无障碍语义 -- label forhex classinput-label-hidden十六进制色值/label input classinput idhex placeholder#6911d4 /6.3 其余控件与图标组件目录中还包含checkbox.css、radio-button.css、select.css、switch.css、icon.css见 components 目录它们与按钮、输入框共用同一套明暗令牌--db/lb-*、--da/la-*因此只要保证根节点挂有data-theme勾选框、单选、下拉、开关与图标在明暗主题下都会自动跟随配色。这些控件同样建议显式声明 disabled 与 focus-visible 态保证键盘可操作性。generic.css中还有一个值得注意的细节全局为::-webkit-scrollbar定义了 5px 宽的细滚动条并去除了 track 背景插件内出现滚动区域如长列表时会呈现与 Penpot 一致的轻量滚动条观感。七、图标约定与 Feather Icons 保持一致官方 README 的 Icons 一节给出明确建议Penpot 插件推荐使用 Feather Icons 图标集以保证图标风格线性、圆角、1.5px 级别的纤细笔触与 Penpot 自身的设计语言一致。Feather 是 MIT 许可的知名开源图标集图标以svg内联或 Sprite 方式使用均可。包内src/lib/icons/也自带了一个chevron-bottom.svg下拉箭头作为图标资源的放置范例供需要随包分发图标的插件参考其组织方式。在图标实现层面可参照组件层icon.css的存在推断图标应作为独立组件处理与文字对齐、颜色继承建议让stroke/fill使用currentColor并挂靠前景色令牌从而在主题切换时无需单独适配。八、从源码到发布构建与版本管理该库的构建信息集中在 package.json{ name: penpot/plugin-styles, version: 1.5.0, scripts: { build: node ../../tools/scripts/build-css.mjs, lint: echo 0 } }构建脚本build调用仓库plugins目录下tools/scripts中的build-css.mjs负责把src/lib/styles.css及其递归的import子文件core 与 components 各 CSS聚合、处理为对外发布的styles.css。因此使用者import penpot/plugin-styles/styles.css拿到的实际是一份合并产物而源码侧的模块化拆分只服务于可维护性。工程元数据位于 project.json声明这是一个projectType: library的独立库属于仓库基于 Nx 组织的前端工作区$schema指向根node_modules/nx的 schema。对插件作者而言日常开发不需要关心构建细节只有当你 fork 该包自行定制样式例如调整品牌强调色或新增企业主题时才需要修改src/lib/core/下的令牌源文件并重新执行 build。九、接入清单与最佳实践把以上内容收敛为一份可执行清单安装npm install penpot/plugin-styles或 pnpm 对应命令引入在插件入口样式执行import penpot/plugin-styles/styles.css;声明主题在插件容器根元素设置data-themedark或data-themelight建议跟随宿主用色或提供用户可切换项不设置时样式规则中依赖--background-*等语义变量的部分没有取值来源因此该步骤不可省略布局与排版优先使用body-*、title-*、headline-*、display工具类和--spacing-*、--font-*令牌保证与 Penpot 视觉节律一致控件按钮使用data-appearanceprimary | secondary危险操作叠加data-variantdestructive输入框使用.input并善用.input-label-hidden、.error、.success勾选框/单选/开关等直接采用包内对应组件类校验反馈充分利用原生:invalid与--error-500/--success令牌让错误提示与主题自洽自定义业务色涉及选色展示的功能复用--app-*色板令牌与 Penpot 内置色板保持一致图标采用 Feather Icons 风格图标颜色使用currentColor透传保证明暗主题自动适配主题健壮性若插件运行环境存在严格 CSP 或离线场景需将 Work Sans 字体自托管并替换 fonts.css 中的远程导入。十、结语penpot/plugin-styles的定位很克制它只交付 CSS但通过语义令牌 双主题 组件类的三层设计把 Penpot 的界面设计语言完整地注入插件侧。对插件作者而言这意味着一份低成本的 UI 一致性与明暗主题适配方案对想深入理解 Penpot 设计系统的读者plugins/libs/plugins-styles/src/lib 目录则是一份相当干净的 CSS 架构参考——从swatches.css的令牌定义、generic.css的主题重映射到components/button.css的分状态实现都可以作为自研设计系统时对照学习的范本。【免费下载链接】penpotPenpot: The open-source design platform for Product teams that need scalable collaboration.项目地址: https://gitcode.com/GitHub_Trending/pe/penpot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考