skeleton

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skeleton UI Skill

Skeleton UI 技能

Full Reference: See theming.md for Design Tokens, Custom Themes, Theme Switching, Data Display (Cards, Tables, Avatars), Feedback (Toast, Modal), Navigation (Tabs, Stepper, Pagination), and Stores Setup.

完整参考文档：查看theming.md获取设计令牌、自定义主题、主题切换、数据展示（卡片、表格、头像）、反馈组件（提示框、模态框）、导航组件（标签页、步骤条、分页）以及状态管理配置相关内容。

When NOT to Use This Skill

不适用场景

React/Vue/Angular projects - Skeleton is Svelte-only
Plain HTML/CSS - Skeleton requires Svelte and Tailwind CSS
Headless UI needs - Skeleton provides styled components
SvelteKit not used - Skeleton is optimized for SvelteKit

React/Vue/Angular项目 - Skeleton仅支持Svelte
纯HTML/CSS项目 - Skeleton依赖Svelte和Tailwind CSS
无头UI需求 - Skeleton提供带样式的组件
未使用SvelteKit - Skeleton针对SvelteKit优化

Installation

安装步骤

bash

undefined

bash

undefined

Create new SvelteKit project

创建新的SvelteKit项目

npx sv create my-app cd my-app

Add Skeleton

添加Skeleton

npx @skeletonlabs/skeleton-cli add skeleton

Or manual installation

或手动安装

npm install @skeletonlabs/skeleton @skeletonlabs/tw-plugin npm install -D tailwindcss postcss autoprefixer

undefined

npm install @skeletonlabs/skeleton @skeletonlabs/tw-plugin npm install -D tailwindcss postcss autoprefixer

undefined

Configuration

配置步骤

tailwind.config.js

javascript

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'],
      },
    }),
  ],
};

javascript

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

css

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

css

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

app.html

html

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

html

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

Layout Components

布局组件

AppShell

svelte

<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>

svelte

<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>

Form Components

表单组件

Buttons

按钮

svelte

<!-- Variants -->
<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>

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

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

svelte

<!-- 样式变体 -->
<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>

Inputs

输入框

svelte

<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>

svelte

<label class="label">
  <span>邮箱</span>
  <input class="input" type="email" placeholder="输入邮箱" />
</label>

<label class="label">
  <span>留言</span>
  <textarea class="textarea" rows="4"></textarea>
</label>

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

Checkbox, Radio & Toggle

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

svelte

<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>

svelte

<label class="flex items-center space-x-2">
  <input class="checkbox" type="checkbox" />
  <span>接受条款</span>
</label>

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

<label class="flex items-center space-x-2">
  <input class="toggle" type="checkbox" />
  <span>深色模式</span>
</label>

Data Display

数据展示组件

Cards

卡片

svelte

<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>

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

svelte

<div class="card p-4">
  <header class="card-header">
    <h3 class="h3">卡片标题</h3>
  </header>
  <section class="p-4">卡片内容</section>
  <footer class="card-footer">
    <button class="btn variant-filled-primary">操作</button>
  </footer>
</div>

<!-- 可交互卡片 -->
<a href="/item/1" class="card card-hover p-4">点击跳转</a>

Lists

列表

svelte

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

svelte

<nav class="list-nav">
  <ul>
    <li><a href="/">仪表盘</a></li>
    <li><a href="/users">用户</a></li>
  </ul>
</nav>

Utility Classes

工具类

svelte

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

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

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

svelte

<!-- 令牌感知背景色 -->
<div class="bg-surface-100-800-token">适配主题</div>

<!-- 排版 -->
<h1 class="h1">一级标题</h1>
<h2 class="h2">二级标题</h2>
<p class="lead">引导段落</p>

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

Design Tokens

设计令牌

css

/* 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

css

/* 基础颜色 */
--color-primary-500
--color-secondary-500
--color-surface-500

/* 颜色梯度：50-950 */
--color-primary-50    /* 最浅 */
--color-primary-500   /* 基础色 */
--color-primary-950   /* 最深 */

/* 排版 */
--base-font-family
--heading-font-family

/* 圆角 */
--theme-rounded-base
--theme-rounded-container

Using Design Tokens

使用设计令牌

svelte

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

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

svelte

<!-- 通过Tailwind类 -->
<div class="bg-primary-500 text-on-primary-token">
  主色调背景
</div>

<!-- 通过CSS变量 -->
<div style="background-color: rgb(var(--color-primary-500));">
  自定义样式
</div>

Best Practices

最佳实践

Always initialize stores in root layout
Use variant classes for consistent styling
Leverage design tokens for theme-aware colors
Use
-token
suffix for auto dark/light switching
Keep accessibility in mind - use semantic HTML

始终在根布局中初始化状态管理
使用变体类保证样式一致性
利用设计令牌实现主题适配颜色
使用
-token
后缀实现自动明暗模式切换
注重无障碍性 - 使用语义化HTML

Anti-Patterns

反模式

Anti-Pattern	Why It's Wrong	Correct Approach
Not initializing stores	Modals, toasts won't work	Call `initializeStores()` in layout
Forgetting `skeleton.css`	Components unstyled	Import before Tailwind directives
Using raw Tailwind colors	Breaks theming	Use design tokens
Missing `data-theme`	Theme not applied	Add to `<body>`
`darkMode: 'media'`	Wrong dark mode	Set `darkMode: 'class'`

反模式	问题原因	正确做法
未初始化状态管理	模态框、提示框无法正常工作	在布局中调用 `initializeStores()`
忘记引入 `skeleton.css`	组件无样式	在Tailwind指令前导入
使用原生Tailwind颜色	破坏主题定制	使用设计令牌
缺少 `data-theme` 属性	主题未生效	添加到 `<body>` 标签
设置 `darkMode: 'media'`	深色模式异常	设置为 `darkMode: 'class'`

Quick Troubleshooting

快速排查指南

Issue	Solution
Modal not showing	Call `initializeStores()` in root layout
No styling	Import `skeleton.css` in app.postcss
Theme not applying	Add `data-theme="skeleton"` to body
Dark mode broken	Set `darkMode: 'class'` in tailwind.config
Toast not appearing	Add `<Toast />` to root layout

问题	解决方案
模态框不显示	在根布局中调用 `initializeStores()`
无样式显示	在app.postcss中导入 `skeleton.css`
主题未生效	为body添加 `data-theme="skeleton"`
深色模式失效	在tailwind.config中设置 `darkMode: 'class'`
提示框不出现	在根布局中添加 `<Toast />` 组件

Reference Documentation

参考文档

Components Cheatsheet

组件速查表