# SnowUI 组件样式使用指南

来源指纹：eff08e32ec408bc4。

## 先确定修改的范围

首次使用或修改 SnowUI 先读目标版本完整 [LICENSE](https://snowui.dev/LICENSE)，同任务、同版本、同已确认范围去重。各方案在其授权用途、项目与人数内允许必要的源码、样式、交互修改与框架移植；Free 源码不因免费而禁止修改，也不因下载成功而获得线上真实产品或再分发权益。

先读 [设计指南](https://snowui.dev/llms/design-system.md)，再读取命中组件的 `api.md`、复杂组合所需的 `reference.md` 和定制所需的 `styles.md`。例如 [Button API](https://snowui.dev/llms/components/button/api.md) 与 [Button 样式](https://snowui.dev/llms/components/button/styles.md)。不默认加载所有覆盖变量、整库源码或内部维护资料。

## 样式选择与改写顺序

用户与 AI 必须遵守两点：**优先通过组件公开 Props 匹配合适的样式；尽可能保留组件原有样式。** 默认视觉已满足需求时直接使用，不为了“定制”重写颜色、尺寸、圆角或所有状态。

Props 包括该组件实际公开的 `variant`、`size`、`emphasis`、颜色等样式参数。先核对 API 中的可选值与默认值，用最接近需求的现有样式；不要猜测不存在的字段，也不要用 CSS 重新实现已有 variant。确有产品或设计差异时，再按以下推荐顺序只修改必要部分：

| 顺序 | 使用方式 | 判断依据 |
| --- | --- | --- |
| 1 | 组件公开 Props | 能表达需求就结束样式改写；默认值已经合适时无需显式覆盖。 |
| 2 | 用户自己的 `class`，或项目已有的 Tailwind 工具类 | 复用应用样式，通过组件实际公开的根 / role 或已登记 override 调整必要视觉；Tailwind 属于 class 方式，不是另一套后置优先级。 |
| 3 | 该实例的 `style` | 用于仅此实例的一次性差异或动态值；先核对真实公开入口，不把一项差异扩散为全局重设。 |

外部应用可以采用自己的 CSS / Tailwind 与设计值，不要求安装 SnowUI 一方样式工具，也不要求自定义 class 必须有两个使用点。已有 Tailwind 时沿用它；不要只为改一个组件就额外引入新样式框架。需要保持主题与缩放协调时，推荐使用同类别 SnowUI Token；指定设计稿的精确值仍要忠实匹配，不能用“保留原样”静默忽略设计差异。

这是 AI 选择方案的顺序，**不是浏览器 CSS 层叠强度排序**。层、特异性、声明位置与 inline style 会影响实际结果；class 字符串的先后顺序不能保证覆盖。样式没有生效时，先核对被修改属性的公开 owner 和登记 override，而不是堆 `!important` 或私有选择器。

## 用 Props 保留现有视觉

例如 Button 的现有公开参数已经能表达按钮变体和尺寸：

```svelte
<script lang="ts">
  import '@snowui-design-system/components/styles';
  import { Button } from '@snowui-design-system/components';
</script>

<Button variant="filled" size="md">保存修改</Button>
```

外部应用只需组件包与其包内样式。应用覆盖通常在组件样式之后加载；同时检查工具链的 CSS layer，因为“后加载”本身不能保证覆盖。需要使用 SnowUI 参数时查 [Token 目录](https://snowui.dev/llms/tokens.md)，Figma 来源另读 [Figma 映射指南](https://snowui.dev/llms/figma.md)。可选的 `snowui-base.css` 会让页面自己的普通 `<a href>` 默认不带下划线，并以 `Black40 → Black100` 显示 hover / 键盘焦点反馈。样式表明确加了下划线时，非禁用 hover 会隐藏它；SnowUI 的 `Link`、`Button href` 仍由各自组件控制。想让普通链接使用 `Black100 → Black40`，可在该链接或其容器设置 `--snowui-native-link-color: var(--black-100)` 和 `--snowui-native-link-hover-color: var(--black-40)`。直接写应用自己的 `color` 时，应用需同时定义自己的 hover 色；基础样式无法从已计算颜色自动推导反向色。直接写在元素 `style` 上的下划线也需由应用定义 hover 装饰，基础规则不会用 `!important` 覆盖它。没有导入 `snowui-base.css` 的在线 AI 宿主不会得到这些普通链接样式。

## 确需改写时先用自己的 class

例如产品明确需要此按钮采用较小圆角，而 Button 的公开 Props 没有对应入口，可以在用户自己的应用样式表中设置实际登记的圆角 override：

```css
.project-action {
  --snowui-button-radius-override: var(--radius-2);
}
```

再把该 class 传给目标实例，保留已选的变体和尺寸：

```svelte
<script lang="ts">
  import '@snowui-design-system/components/styles';
  import { Button } from '@snowui-design-system/components';
</script>

<Button variant="filled" size="md" class="project-action">保存修改</Button>
```

Tailwind 也通过组件实际支持的 `class` 入口使用。先确认项目已经生成相应工具类，并确认该类调整的是公开目标；需要时在 class 中设置已登记的 override。Button 的默认背景由组件自己的背景层绘制，给根节点加 `bg-*` 或 `background-color` 不保证改到该层；应查其 `styles.md` 中真实的 `--snowui-button-background-override`，不能查找私有后代来补丁。

## 最后使用实例 style

同样的圆角若只服务当前实例的一次性或动态差异，可以通过实例 style 设置同一个公开入口：

```svelte
<script lang="ts">
  import '@snowui-design-system/components/styles';
  import { Button } from '@snowui-design-system/components';
</script>

<Button variant="filled" size="md" style="--snowui-button-radius-override: var(--radius-2);">保存修改</Button>
```

不对同一属性同时写互相冲突的 Props、class 和 style。更具体的单实例 style 可能覆盖应用 class；修改前确认这是期望的局部差异，修改后仍验证原有状态。

## 根宿主、默认内置子项和显式子项

| 目标 | 公开入口 | 作用边界 |
| --- | --- | --- |
| 组件根宿主 | 实际公开的 `class` / `style` 与该组件已登记 override | 作用于文档说明的根或 role；不推定能改任意后代。 |
| 组件默认生成的内置子项 | 文档明确支持的 `parts.ComponentName` | 配置对应子组件的公开 Props；业务值、身份、角色、事件和受控状态仍按宿主契约。 |
| 调用方显式写出的 child | 直接给 child 传其公开 Props | 不自动消费父级 parts；选择状态、键盘与 ARIA 仍遵守组合协议。 |
| 页面自己的容器 | 页面布局与应用样式 | 控制区域排列、宽度、间距与响应式；不复制组件内部布局和状态。 |

`parts` 是定位默认子组件的入口，不是排在 style 后面的另一种改写方法：先用 `parts.Child` 中该 child 的公开 Props，确有需要再用它实际支持的 class / style。显式写出的 child 自己配置，不能假定父级 parts 会自动改它。

例如 SearchPopup 的默认输入允许通过 `parts.SearchInput` 配置提示与可访问名称：

```svelte
<script lang="ts">
  import '@snowui-design-system/components/styles';
  import { SearchPopup } from '@snowui-design-system/components';
</script>

<SearchPopup
  items={[{ value: 'files', label: '项目文件', href: '/files' }]}
  parts={{ SearchInput: { placeholder: '搜索项目', 'aria-label': '搜索项目' } }}
/>
```

这是 [SearchPopup](https://snowui.dev/llms/components/search-popup.md) 的实际公开入口，不是所有组件都提供的通用字段。SearchInput 自己以 Input 为宿主，兼容 Props 在根级平铺，不提供 `parts.Input`；需要它生成的子项配置时读其实际 API，不从结构猜 parts 名称。

## 使用已登记的视觉覆盖

组件 `styles.md` 列出当前运行时消费的公开 `--snowui-…-override`。override 是 class / style 内可以设置的公开值，不是越过 Props 的捷径。先确认 Props 不能表达需求，再根据上面的顺序与实际作用域选择用户 class 或实例 style；不要把局部差异无意间传给全部后代。

只有应用明确需要一类组件统一变化时才扩大 class / 主题覆盖的作用域，不默认把实例需求写到 `:root`。不要设置未登记的内部变量、查询组件私有 class / DOM、用高特异性选择器或 `!important` 抢占状态样式。

采用 SnowUI Token 时，颜色、字号、行高、边框、圆角、尺寸、内边距和间距选择各自参数族，不因为数值相同而互相借用。字号与相应行高成对设置，例如 `--text-14` / `--leading-14`；组件公开 size 能一起调整时优先使用 size。主题颜色与几何梯度是不同范围，只换主题不承诺同时改变布局、结构、交互或动效。

## 整条边缘的渐进式背景模糊

需要在页面边缘叠加透明渐进式背景模糊时，可用组件包导出的 `createEdgeProgressiveBlurStyles`，不必复制 SnowUI 站点的四层样式。`direction` 支持 `top-to-bottom`、`bottom-to-top`、`left-to-right`、`right-to-left`；`extent` 设置垂直方向的高度或水平方向的宽度，默认 `80px`。`position` 可选 `absolute`（默认）或 `fixed`，`zIndex` 按页面层级设置。渲染返回的 `containerStyle` 和 `layers`，给外层加 `aria-hidden="true"`；装饰层不接收鼠标事件，也不覆盖正文。浏览器不支持 `backdrop-filter` 时，透明层保持内容可读。

```svelte
<script lang="ts">
  import { createEdgeProgressiveBlurStyles } from '@snowui-design-system/components';
  const blur = createEdgeProgressiveBlurStyles({ direction: 'bottom-to-top', extent: '6rem' });
</script>

<div style="position: relative; min-height: 12rem;">
  <p>Readable content</p>
  <span style={blur.containerStyle} aria-hidden="true">
    {#each blur.layers as layer (layer.index)}<span style={layer.style}></span>{/each}
  </span>
</div>
```

## 公开配置无法表达时

先核对版本、候选组件与公开契约。确需调整实现时，只修改合法项目必要的组件和关联能力，并保留完整 LICENSE 与第三方声明；记录所改 API、状态和样式，避免升级时丢失。移植也须保留许可与原有行为，不得把修改版或移植版另行发布为通用组件资源。

验证实际页面的浅深主题、长文本、窄屏、focus、hover、disabled 和相关状态；确保文字可读、命中区与布局稳定。截图只能证明记录的视口、主题与状态，不能替代键盘和真实交互测试。同任务已核对的许可与文档继续复用，不逐组件重复验读。