PlaceholderUI

使用单个配置对象重新命名的Svelte 5组件库。 表单、覆盖、布局、数据显示、TipTap富文本编辑器和 CodeMirror代码编辑器，所有样式都通过一组 --ui-* CSS的令牌。

• 在每个组件上添加5个runes、TypeScript和类型化的道具
• 带有持续性的浅色/深色/系统主题
• 中性默认调色板；在一个电话中交换您自己的颜色，字体和徽标
• 150+图标导出为原始SVG字符串

安装

pnpm add @placeholderco/placeholder-ui

同行的依赖: svelte ^5.

快速启动

把你的应用包裹起来 AppShell （它加载基本样式表），然后使用组件：

<script lang="ts">
    import { AppShell, Navbar, Button } from '@placeholderco/placeholder-ui';
</script>

<AppShell>
    <Navbar appNav={{ href: '/', text: 'My App' }} />
    <Button variant="primary">Save</Button>
</AppShell>

或跳过 AppShell 然后自己导入标记样式表：

import '@placeholderco/placeholder-ui/app.css';

品牌

所有与颜色和字体相关的内容都解析为 --ui-* 自定义属性 有两种方法可以给图书馆打上品牌。

1. 配置对象（推荐）

// src/routes/+layout.svelte (or any startup code)
import { applyTheme } from '@placeholderco/placeholder-ui';
import logo from '$lib/logo.svg?raw';

applyTheme({
    colors: {
        primary: '#1e3a5f', // dark brand colour: solid buttons, headings
        accent: '#93c5fd', // light brand colour: highlights, dark-mode accent
        tertiary: '#a5f3fc' // supporting color: links use its readable text color
    },
    fontFamily: "'Inter', system-ui, sans-serif",
    logo // raw SVG, rendered by <Logo />
});

每个品牌的颜色都有独立的 *HoverColor 和 *PressedColor 设置: primaryHoverColor， accentHoverColor， tertiaryHoverColor， primaryPressedColor， accentPressedColor 和 tertiaryPressedColor. 它们由坚实、轮廓和微妙的控制共享；微妙的变体使用 半透明的悬停填充在适当的地方。

这三种颜色都有两个相同的文本角色：

例如, primaryTextColor 样式化静止时的主要轮廓按钮，而 primaryContrastColor 为填充的主按钮上的标签设置样式。 focusColor， link 和 linkHover 控制键盘焦点环和链接 独立。更改悬停颜色不会更改其他角色。

所有角色覆盖都是可选的。默认情况下，主悬停使用重音文本 颜色，重音悬停使用三级悬停，三级悬停使用重音。主要按 从它的底色变暗。Primary文本默认为Primary；口音和 三级文本颜色比它们的基色变暗。重音和三级 按下的颜色由三级调亮（或省略三级调时的重音）。 主对比度默认为白色；重音和三级对比度默认为主要对比度。

对于现有配置，请替换 primaryDark 与 primaryPressedColor， accentDark 与 accentTextColor, tertiaryDark 与 tertiaryTextColor. 取代 tertiaryLight 与 accentPressedColor 和 tertiaryPressedColor 来保持两组受压状态。分别设置悬停的颜色 定制的交互。重命名 primaryContrast 和 accentContrast 来 primaryContrastColor 和 accentContrastColor． 它们的CSS令牌也获得 -color 后缀。CSS重写使用相应的串大小写名称， 如 --ui-primary-hover-color 和 --ui-tertiary-text-color.

明暗值

配置中的所有内容都是亮模式值，也适用于暗模式。 当暗模式处于活动状态时，添加一个 dark 用相同的块 形状。只有你的名字被覆盖；色度是根据每种颜色得出的。

applyTheme({
    colors: { primary: '#1e293b', accent: '#fbbf24', tertiary: '#7dd3fc' },
    logo,
    dark: {
        colors: { accent: '#fde68a', link: '#fde68a' },
        fontFamily: "'Inter', system-ui, sans-serif", // optional
        logo: darkLogo // optional
    }
});

applyTheme 注入一个 <style> 元素 :root 规则和a :root.dark 规则，因此值与现有值切换 .dark 类。

为了避免默认调色板在第一次绘制时闪烁，请呈现相同的配置 作为服务器端的CSS：

import { themeToCss } from '@placeholderco/placeholder-ui';
const css = themeToCss(myTheme); // ":root { ... }\n:root.dark { ... }"

然后把它放在 <style> 标签 app.html 或者你的根布局头。

2. 纯CSS

覆盖在库之后加载的任何样式表中的标记：

:root {
    --ui-primary-rgb: 30 58 95;
    --ui-primary-rgbc: 30, 58, 95;
    --ui-primary: rgb(var(--ui-primary-rgb));
    --ui-primary-hover-color: #1d4ed8;
    --ui-primary-pressed-color: #12253d;
    --ui-primary-text-color: #1e3a5f;
    --ui-primary-contrast-color: #ffffff;
    --ui-accent-rgb: 147 197 253;
    --ui-accent-rgbc: 147, 197, 253;
    --ui-accent: rgb(var(--ui-accent-rgb));
    --ui-accent-hover-color: #a5f3fc;
    --ui-accent-pressed-color: #cffafe;
    --ui-accent-text-color: #1d4ed8;
    --ui-accent-contrast-color: #1e3a5f;
    --ui-tertiary: #a5f3fc;
    --ui-tertiary-hover-color: #93c5fd;
    --ui-tertiary-pressed-color: #cffafe;
    --ui-tertiary-text-color: #0e7490;
    --ui-tertiary-contrast-color: #1e3a5f;
    --ui-focus-color: #1d4ed8;
    --ui-font-family: 'Inter', system-ui, sans-serif;
}

完整的令牌列表以及对每个角色的注释位于顶部 src / lib / app.css.

色的角色

在选择颜色时保持这些关系，因为成分会假设它们：

字体

库从不捆绑一个字体。集 --ui-font-family (或 fontFamily 在 配置)并自己加载字体 @font-face 或者一个 <link>.

标志

<Logo /> 渲染，按优先顺序：它 svg 道具、商标注册 通过 applyTheme({ logo }) / setLogo()，或通用占位符。使用 fill="currentColor" 在您的SVG中，使其遵循主题，或注册一个单独的 深色图案logo dark.logo / setLogo(light, dark).

变体

按钮，徽章，动作图标，下拉菜单，手风琴和进度条共享颜色 以令牌命名的变体： primary， accent， tertiary,再加上 -outline 和 -subtle 形式和中性词 secondary， white， danger 和 auto-* 变体。

使用额外的彩色按钮 tertiary， tertiary-outline 和 tertiary-subtle，通过配置 colors.tertiary 和现有的 --ui-tertiary* 令牌。这个 secondary， secondary-subtle 和 secondary-selected 变体保留其原有的中性风格；现有的 应用程序不需要重命名它们。现有的三级颜色和按钮样式 都被保留了下来，为家庭增加了轮廓支持。

主题（浅色/深色）

import { themeState, setTheme } from '@placeholderco/placeholder-ui';

setTheme('dark'); // 'light' | 'dark' | 'system'
themeState.isDarkMode; // reactive boolean

这个 .light / .dark 类应用于 <html>． 在您自己的组件中使用 :global(.dark) .my-class { ... } 或者表面符号(--page-bg， --paper-body-bg， --text-color， --border-color,……)。

开发

pnpm install
pnpm run dev      # showcase app at http://localhost:5173
pnpm run check    # svelte-check
pnpm run build    # library + showcase
pnpm run format

src/lib 是出版图书馆； src/routes 是橱窗。每一个 组件下有一个演示页面 src/routes/components/<name>.

许可证

麻省理工学院