# SnowUI 设计使用指南

来源指纹：e8b346c107de1348。

## 使用前先阅读许可

首次采用 SnowUI，先阅读目标安装包或源码随附的完整 LICENSE；官方阅读入口为 [LICENSE](https://snowui.dev/LICENSE)。同任务、同版本与已确认主体 / 产品 / 用途 / 人数只读一次，事实或发布目标变化时再核对。下载或安装成功不能证明额外授权，网站最新文档也不追溯改变旧版本许可。

Free 按许可使用，不要求注册、账户、公钥或付费文件；具体产品的本地或受控云端开发最多 1 个项目、1 名开发者。学习测试、纯组件 Demo 与许可允许的内容表达免计项目，纯 Demo 可以免费公开。真实产品的草稿计入所属产品，线上使用或交付前核对 Pro / Team；不按目录、AI 账号或电脑增加权益。各方案在授权范围内允许必要样式、交互修改与框架移植，整体体系抽取、竞品及再分发等共同限制仍由完整许可解释。

缺失证据先核对已有许可；明确权益不足时按 LICENSE 说明缺口与最低适用方案，只暂停依赖缺口的操作。购买入口未开放时如实说明，不编造网址。计划文字、安装结果和普通成功页面不作为付费证明。

## 从设计稿开始

将画面拆为页面结构、导航、操作、输入、内容、数据展示和反馈。先说明每个区域的行为，再读 [组件选型指南](https://snowui.dev/llms/component-selection.md) 并查 [组件目录](https://snowui.dev/llms/components.md) 或 [AI · 关键词检索](https://snowui.dev/llms/find?q=%E6%96%87%E4%BB%B6%E8%A1%A8%E6%A0%BC)。常驻记录不自动等于 Toast，页面右栏不自动等于 SidePanel；按职责和公开契约选择。

组件拥有默认视觉、键盘 / ARIA、交互和状态；页面拥有路由、业务数据、请求、权限与页面编排。先选合适组件，用公开 Props（含实际支持的 variant / size）匹配所需样式，尽可能保留原有视觉，再安排页面布局。开始使用组件时阅读一次 [样式选择与改写顺序](https://snowui.dev/llms/styling.md#%E6%A0%B7%E5%BC%8F%E9%80%89%E6%8B%A9%E4%B8%8E%E6%94%B9%E5%86%99%E9%A1%BA%E5%BA%8F)，同任务复用；常规消费不复制私有 DOM、class 或状态逻辑，必要源码修改按许可及相关契约处理。

读取 Figma 设计时继续看 [Figma 映射指南](https://snowui.dev/llms/figma.md)。截图只证明可见状态，不能证明精确数值、变量绑定、隐藏交互或响应式规则。没有标注的参数可说明所选现有值；明确设计值无法映射时记录差异，不静默替换为任意颜色、间距或圆角。

## 安装与样式入口

当前官方组件运行包面向 Svelte 5；先引入组件样式，再加载应用覆盖。

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

<Button>保存修改</Button>
```

外部应用可以只采用组件及其包内样式，无须引入 SnowUI 一方网站的全部初始化和 utilities。导出与参数以实际安装版本为准。Frame 是唯一通用宿主，按其公开文档使用，不从旧版资料推定另一个宿主或未支持字段。

纯 HTML、React 或在线 AI 工具不一定能直接运行 Svelte。先确认框架、依赖和文件能力；许可允许的项目内移植与官方已提供对应框架运行包是两件事，不能伪造安装或兼容结果。

## 页面布局与响应式

普通 `main`、`section`、`aside` 和 `footer` 表达页面语义，导航与控件仍优先使用对应组件。先确定 padding / gap 的拥有者，避免父子两层重复间距、圆角和外壳。组件外可采用已引入的页面 utilities；只使用组件包时使用公开 Token 与最小页面样式，不假设可选工具类已经加载。

### Frame 通用布局

| 模式 | 适用需求 | 公开入口 |
| --- | --- | --- |
| 三槽 | 附件保持自身尺寸，正文占剩余空间 | `row`，附件 `as="leading"` / `as="trailing"`，正文不声明附件角色 |
| 单行图文／姓名／日期 | 名称保持同排，附件不缩小；文字放不下时截断并可读全文 | `singleLine`＋`as="leading/trailing"`＋`Text lines={1}` |
| 首行对齐 | 图标与多行文字的第一行对齐 | `row firstLine`，沿用三槽角色 |
| Pin | 角标等脱离正常内容流 | `as="pin-*"`，位置按真实公开值选择 |

完整边界、行高与组合规则按需读取 [Frame 使用手册](https://snowui.dev/llms/components/frame/reference.md)。单行标签与允许换行的正文按语义分别声明singleLine或firstLine；首行对齐须明确声明，不把所有横向容器自动变成首行对齐；不靠固定高度、负 margin 或页面私有补丁替代已有布局能力。

窄屏按设计与内容约束调整页面排列、换行、截断或局部滚动；不继续压缩文字和功能图标。继承 context、组件 size 与实际宽高分别由其公开 API 定义，不能互相当作数值编号。

## 颜色：先语义，再数值

以下参数用于沿用或还原 SnowUI 设计。外部应用需要自己的设计值时，按样式指南在公开入口做最少改写；不把一方维护的 Token / utilities 准入要求强加给用户项目。

颜色 Prop 只在该组件已经公开支持时使用，按文档选择 `Brand`、`Primary`、`Black40`、`Background1` 等语义值。页面颜色采用相应 `var(--brand)`、`var(--black-40)`、`var(--background-1)`；Black / White 随主题变化，StaticBlack / StaticWhite 才表示固定黑白。

照片与品牌资产保留资源语义；它们不使普通文字、背景和控件自动获得任意色值。Figma Style / Variable 的名称、模式与主题要一起记录，不将截图取色或浅色 HEX 当作唯一 Token 值。具体名称查 Figma 指南，声明与条件查 [Token 目录](https://snowui.dev/llms/tokens.md)。

## 几何与排版参数

| 目标 | 参数族 | 使用原则 |
| --- | --- | --- |
| 字号与行高 | `--text-*` / `--leading-*` | 配对选择同档编号，保持文字可读 |
| 尺寸 | `--size-*` | 用于尺寸，不代替字号或组件逻辑 size |
| 内边距 | `--padding-*` | 内容与外壳边缘之间的距离 |
| 间距 | `--gap-*` | 相邻元素和页面区域的空间 |
| 边框 | `--border-*` | 边框宽度，不借作间距 |
| 圆角 | `--radius-*` | 普通梯度与全圆角分别按实际语义选择 |

Token 编号不是统一的 px，页面工具类后缀也不一定与 Token 编号相同。精确声明从 CSS 生成的 Token 目录读取，rem 参数会受根字号影响；不另抄固定数值表，不因为终值相同而借用其他类别。

```html
<section style="display: flex; flex-direction: column; gap: var(--gap-3); padding: var(--padding-4); background: var(--surface-1);">
  <h2 style="font-size: var(--text-18); line-height: var(--leading-18);">项目文件</h2>
</section>
```

此例仅表达页面区域和文字；需要 Card、表单或弹层等已有视觉 / 行为时先用相应组件。

## 修改样式应该在哪里

优先通过组件公开 Props 匹配样式并尽量保留原有视觉；确需改写时先用用户自己的 class（包括项目已有 Tailwind），再用实例 style。完整顺序与公开根 / parts / child / override 的作用域见 [样式修改指南](https://snowui.dev/llms/styling.md#%E6%A0%B7%E5%BC%8F%E9%80%89%E6%8B%A9%E4%B8%8E%E6%94%B9%E5%86%99%E9%A1%BA%E5%BA%8F)，这里不另设一套优先级。需要定制时再按需读目标组件的 `styles.md`。

不要给每个组件强制一个圆角、设置未公开的内部变量或假造 parts。组件 Token 与独立 utilities 的计算链可能不同，局部覆盖和全局主题的作用域需要分别验证。必要源码修改保留目标版本完整 LICENSE 与第三方声明，并记录升级与框架迁移边界。

## 完成还原前的检查

- 每个区域有明确组件或普通语义结构的选择依据，导出和 API 符合实际版本。
- 颜色、字号 / 行高、尺寸、padding、gap、border 和 radius 对应正确参数族，明确设计差异没有隐藏。
- 当前用途与开发者 / 项目范围已经核对，付费受限操作没有靠计划文字放行；同任务核对结果合理复用。
- 在真实页面检查结构、内容、布局、padding 所有权、对齐、长文本、窄屏、浅深主题和必要状态，再检查键盘及无障碍。

代码检查或截图不能单独证明隐藏交互、所有响应式场景和授权范围。缺什么再读取命中组件的 API、types、reference、styles 或少量示例，不默认加载整个源码库。

## Figma 社区与设计资料

[SnowUI Design System 社区获取入口](https://www.figma.com/community/file/1388431032861751537)、[公开组件／变量对照](https://snowui.dev/llms/figma-map.md)及[设计系统资料关系](https://snowui.dev/llms/design-system-resources.md)分别按需读取。社区资源、组件公开参考文件与付费订单指定文件是独立入口；获取条件以社区页及已验证订单为准。用户修改自己的副本时提供副本 URL，按页面或集合、名称、类型、mode 与当前值重新定位；原文件 ID 不会自动沿用。