skeleton

Skeleton UI 技能

完整参考：有关设计令牌、自定义主题、主题切换、数据展示（卡片、表格、头像）、反馈（Toast、Modal）、导航（选项卡、步骤条、分页）和 Store 设置，请参阅 theming.md。

何时不应使用此技能

• React/Vue/Angular 项目——Skeleton 仅适用于 Svelte
• 纯 HTML/CSS——Skeleton 需要 Svelte 和 Tailwind CSS
• 需要无头 UI——Skeleton 提供带样式的组件
• 未使用 SvelteKit——Skeleton 针对 SvelteKit 进行了优化

安装

# Create new SvelteKit project
npx sv create my-app
cd my-app

# Add Skeleton
npx @skeletonlabs/skeleton-cli add skeleton

# Or manual installation
npm install @skeletonlabs/skeleton @skeletonlabs/tw-plugin
npm install -D tailwindcss postcss autoprefixer

配置

tailwind.config.js

import { skeleton } from '@skeletonlabs/tw-plugin';

export default {
  darkMode: 'class',
  content: [
    './src/**/*.{html,js,svelte,ts}',
    require.resolve('@skeletonlabs/skeleton').replace(/\/index\.js$/, '/**/*.{html,js,svelte,ts}')
  ],
  plugins: [
    skeleton({
      themes: {
        preset: ['skeleton', 'modern', 'crimson'],
      },
    }),
  ],
};

app.postcss

@import '@skeletonlabs/skeleton/styles/skeleton.css';
@tailwind base;
@tailwind components;
@tailwind utilities;

app.html

<body data-theme="skeleton" class="h-full">
  %sveltekit.body%
</body>

---

布局组件

AppShell

<script>
  import { AppShell, AppBar, AppRail, AppRailTile } from '@skeletonlabs/skeleton';
  let { children } = $props();
</script>

<AppShell>
  <svelte:fragment slot="header">
    <AppBar>
      <svelte:fragment slot="lead">
        <strong>My App</strong>
      </svelte:fragment>
      <svelte:fragment slot="trail">
        <button class="btn variant-filled-primary">Login</button>
      </svelte:fragment>
    </AppBar>
  </svelte:fragment>

  <svelte:fragment slot="sidebarLeft">
    <AppRail>
      <AppRailTile label="Home">🏠</AppRailTile>
      <AppRailTile label="Settings">⚙️</AppRailTile>
    </AppRail>
  </svelte:fragment>

  {@render children()}
</AppShell>

---

表单组件

按钮

<button class="btn variant-filled-primary">Primary</button>
<button class="btn variant-ghost-primary">Ghost</button>
<button class="btn variant-soft-primary">Soft</button>
<button class="btn variant-ringed-primary">Ringed</button>


<button class="btn btn-sm">Small</button>
<button class="btn btn-lg">Large</button>


<button class="btn-icon variant-filled-primary">🔔</button>

输入框

<label class="label">
  <span>Email</span>
  <input class="input" type="email" placeholder="Enter email" />
</label>

<label class="label">
  <span>Message</span>
  <textarea class="textarea" rows="4"></textarea>
</label>

<label class="label">
  <span>Country</span>
  <select class="select">
    <option value="us">United States</option>
    <option value="uk">United Kingdom</option>
  </select>
</label>

复选框、单选框和切换开关

<label class="flex items-center space-x-2">
  <input class="checkbox" type="checkbox" />
  <span>Accept terms</span>
</label>

<label class="flex items-center space-x-2">
  <input class="radio" type="radio" name="plan" value="pro" />
  <span>Pro</span>
</label>

<label class="flex items-center space-x-2">
  <input class="toggle" type="checkbox" />
  <span>Dark mode</span>
</label>

---

数据展示

卡片

<div class="card p-4">
  <header class="card-header">
    <h3 class="h3">Card Title</h3>
  </header>
  <section class="p-4">Card content</section>
  <footer class="card-footer">
    <button class="btn variant-filled-primary">Action</button>
  </footer>
</div>


<a href="/item/1" class="card card-hover p-4">Clickable</a>

列表

<nav class="list-nav">
  <ul>
    <li><a href="/">Dashboard</a></li>
    <li><a href="/users">Users</a></li>
  </ul>
</nav>

---

实用类

<div class="bg-surface-100-800-token">Adapts to theme</div>


<h1 class="h1">Heading 1</h1>
<h2 class="h2">Heading 2</h2>
<p class="lead">Lead paragraph</p>


<span class="badge variant-filled-primary">Badge</span>
<span class="chip variant-filled-tertiary">Chip</span>

---

设计令牌

/* Base colors */
--color-primary-500
--color-secondary-500
--color-surface-500

/* Color shades: 50-950 */
--color-primary-50    /* Lightest */
--color-primary-500   /* Base */
--color-primary-950   /* Darkest */

/* Typography */
--base-font-family
--heading-font-family

/* Border radius */
--theme-rounded-base
--theme-rounded-container

使用设计令牌

<div class="bg-primary-500 text-on-primary-token">
  Primary background
</div>


<div style="background-color: rgb(var(--color-primary-500));">
  Custom styling
</div>

---

最佳实践

1. 始终在根布局中初始化 Store
2. 使用变体类，确保样式一致
3. 利用设计令牌，使用适配主题的颜色
4. 使用 -token 后缀，自动切换深色/浅色模式
5. 注意无障碍性——使用语义化 HTML

反模式

反模式	错误原因	正确做法
未初始化 Store	Modal、Toast 无法使用	在布局中调用 initializeStores()
忘记 skeleton.css	组件没有样式	在 Tailwind 指令之前导入
使用原始 Tailwind 颜色	会破坏主题效果	使用设计令牌
缺少 data-theme	主题不会生效	添加到 <body>
darkMode: 'media'	深色模式设置错误	设置 darkMode: 'class'

快速故障排除

问题	解决方案
Modal 未显示	在根布局中调用 `initializeStores()``
没有样式	在 app.postcss 中导入 skeleton.css
主题未生效	将 data-theme="skeleton" 添加到 body
深色模式失效	在 tailwind.config 中设置 darkMode: 'class'
Toast 未显示	在根布局中添加 <Toast />

参考文档

• 组件速查表