SnowUI 组件样式使用指南

优先用 Props 匹配并保留原样；需要时通过自己的 class、Tailwind 或实例 style 定制。

先确定修改的范围

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

先读设计指南，再读取命中组件的 api.md、复杂组合所需的 reference.md 和定制所需的 styles.md。例如 Button API 与 Button 样式。不默认加载所有覆盖变量、整库源码或内部维护资料。

样式选择与改写顺序

用户与 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 的现有公开参数已经能表达按钮变体和尺寸：

<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 目录，Figma 来源另读 Figma 映射指南。可选的 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：

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

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

<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 设置同一个公开入口：

<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 配置提示与可访问名称：

<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 的实际公开入口，不是所有组件都提供的通用字段。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 时，透明层保持内容可读。

<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 和相关状态；确保文字可读、命中区与布局稳定。截图只能证明记录的视口、主题与状态，不能替代键盘和真实交互测试。同任务已核对的许可与文档继续复用，不逐组件重复验读。