# SnowUI Component Selection Guide

Read the complete [LICENSE](https://snowui.dev/LICENSE) for the installed version before use.

Source fingerprint: `27797c67290505e1`.

<a id="从任务开始找组件"></a>

## Find components from the task

Before using SnowUI, read the complete [LICENSE](https://snowui.dev/LICENSE) for the target version once per task, version, and confirmed scope. For page design and design reproduction, begin with the [design guide](https://snowui.dev/components/design-system). Components are grouped by technical responsibility; names and categories do not indicate a purchase tier or authorization result.

Break the page into regions such as navigation, actions, inputs, content switching, data display, and overlays. Describe what each region must do, then use [AI keyword search](https://snowui.dev/llms/find?lang=en&q=file%20table). Search by actual scenarios such as “file table,” “global search,” “exclusive options,” or “persistent notifications.” Do not choose a component solely by its silhouette or a similar name. Search returns candidates and page patterns; its score is not a visual-match confidence value. If nothing matches, try functional terms and consult the [component directory](https://snowui.dev/components/introduction) as needed. Do not immediately conclude that no component exists.

<a id="按候选读取必要契约"></a>

## Read the necessary contract for each candidate

A candidate’s concise document is at `/llms/components/<slug>.md`, for example [Button](https://snowui.dev/components/button). Confirm its purpose, limits, and import first, then follow links only as needed:

- `api.md`: actual public Props, events, Snippets, and defaults.
- `types.md`: data shapes, bindable fields, and inheritance limits; do not pass excluded base-class properties.
- `reference.md`: complex composition, roles, states, and accessibility boundaries.
- `examples.md` and `.svelte` examples: working patterns; use the relevant image in `images.json` only if appearance remains unclear.
- `styles.md`: read it when this task needs visual customization; follow the [styling guide](https://snowui.dev/components/guides/styling).

For styling, first use the candidate’s actual public Props to match the need and preserve its existing appearance where possible. The ability to write CSS alone is not a reason to recreate the component’s styling. Review the [style selection order](https://snowui.dev/components/guides/styling#%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) once when adopting it, and reuse that result within the same task.

When several regions share a component or capability, reuse what you have read. Do not reload documentation for every instance or read the whole source library, all maintainer rules, or every screenshot by default. Public exports in the docs must match the installed package version; a new API shown online may not exist in an older package.

<a id="按行为区分相近组件"></a>

## Distinguish similar components by behavior

| Actual need | Prefer | How to distinguish |
| --- | --- | --- |
| Open global search / type a query directly / show a search panel | [SearchBox](https://snowui.dev/components/search-box) / [SearchInput](https://snowui.dev/components/search-input) / [SearchPopup](https://snowui.dev/components/search-popup) | Entry point, input, and panel have different responsibilities; the app still owns business search and routing. |
| Switch content panels / choose one mutually exclusive filter | [Tab](https://snowui.dev/components/tab) / [Segmented](https://snowui.dev/components/segmented) | Distinguish content switching from single-choice parameters, even when both look segmented. |
| Show a semantic table / coordinate search, selection, sorting, and pagination | [Table](https://snowui.dev/components/table) / [DataTable](https://snowui.dev/components/data-table) | For data management, first read DataTable composition rules, then combine the Table family, TableToolbar, and Pagination. |
| Single-line input / multiline input / labeled field with feedback | [Input](https://snowui.dev/components/input) / [Textarea](https://snowui.dev/components/textarea) / [Field](https://snowui.dev/components/field) | Field owns the field composition; a placeholder does not replace an accessible label. |
| Persistent activity column / temporary feedback / toggleable detail layer | Ordinary `aside` and list / [Toast](https://snowui.dev/components/toast) / [SidePanel](https://snowui.dev/components/side-panel) | A persistent notice is not a Toast; do not add overlay behavior for an ordinary page column. |

For example, use SearchInput to type a filename directly into a toolbar, rather than SearchBox:

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

  let query = $state('');
</script>

<SearchInput bind:value={query} placeholder="Search files" aria-label="Search files" />
```

`bind:value` synchronizes the input value; the page decides how to filter, request, and display files. If this input belongs to a DataTable toolbar, read the public TableToolbar / DataTable integration instead of rewriting existing data coordination outside it.

<a id="确定组件后再实现页面"></a>

## Implement the page after choosing components

Check in order: direct component reuse → public variant / size → Props, Snippets, events, and composition → page layout. Routes, business data, requests, permissions, and business side effects belong to the app. Keep the component’s visual, keyboard, ARIA, and state behavior through its public contract. Ordinary `main`, `section`, and `aside` page structure can remain; not every decoration or business label needs a new component.

The current SnowUI runtime package targets Svelte 5. The LICENSE permits source modification and framework ports within authorized use; that does not mean this package has ready-made React or other framework APIs. Before using Figma Make, Lovable, or another tool, confirm its project framework. If a port is needed, carry over the relevant component and dependencies, retain the license, and verify behavior. Do not paste a Svelte example into another framework as if it would run unchanged.

At completion, confirm that selection follows behavior and contract, uses the actual API of the installed version, and has read the boundaries for complex compositions. Check necessary interactions, long text, narrow screens, and accessibility states in the real page. Use the [Figma guide](https://snowui.dev/components/guides/figma) for Figma style names and tokens rather than guessing from a screenshot.