# SnowUI Design Guide
Read the complete [LICENSE](https://snowui.dev/LICENSE) for the installed version before use.
Source fingerprint: `e8b346c107de1348`.
## Read the license before you begin
Before adopting SnowUI, read the complete LICENSE included with the target package or source release. The official reading copy is [LICENSE](https://snowui.dev/LICENSE). Read it once for the same task, version, and confirmed subject, product, purpose, and developer count; check again when those facts or the release target change. A successful download or installation does not grant additional rights, and current website documentation does not retroactively change the license of an older version.
Use Free within its license terms; registration, an account, a public key, and a paid credential are not required. Local or controlled cloud development of a real product is limited to one product and one developer. Learning tests, pure component demos, and content expression allowed by the license do not consume a product slot; a pure demo may be published for free. A draft of a real product counts toward that product. Check Pro or Team before online use or delivery. Directories, AI accounts, and computers do not create additional rights. Within each plan’s authorized scope, necessary style and interaction changes and framework ports are allowed; the complete license still governs restrictions on extracting the overall system, competing products, and redistribution.
If evidence is missing, first check existing licenses. When a right is clearly missing, explain the gap and the lowest applicable plan under the LICENSE, and pause only the operation that depends on that right. If purchasing is not open, say so without inventing a URL. Plan text, installation results, and ordinary success pages are not proof of a paid entitlement.
## Start with the design
Break the screen into page structure, navigation, actions, inputs, content, data display, and feedback. Describe what each region does, then read the [component selection guide](https://snowui.dev/components/guides/component-selection) and search the [component directory](https://snowui.dev/components/introduction) or [AI keyword search](https://snowui.dev/llms/find?lang=en&q=file%20table). A persistent activity list is not automatically a Toast, and a right-hand page column is not automatically a SidePanel. Choose by responsibility and public contract.
Components own their default appearance, keyboard and ARIA behavior, interactions, and state. The page owns routes, business data, requests, permissions, and composition. Choose a suitable component first, match the desired appearance with its public Props (including supported variants and sizes), preserve its existing look where possible, then arrange the page layout. When first using components, read the [style selection and override 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 and reuse it during the same task. Ordinary consumers should not copy private DOM, classes, or state logic; necessary source changes must follow the license and relevant contracts.
When reading Figma designs, also consult the [Figma mapping guide](https://snowui.dev/components/guides/figma). A screenshot proves only the visible state. It cannot establish exact values, variable bindings, hidden interactions, or responsive rules. For unspecified parameters, state which existing value you chose. If an explicit design value cannot be mapped, record the difference rather than silently substituting an arbitrary color, spacing value, or radius.
## Installation and styles
The current official component runtime package targets Svelte 5. Import component styles before application overrides.
```svelte
```
External apps may use only the components and their packaged styles; they do not need all initialization and utilities from the SnowUI website. Check exports and Props against the installed version. Frame is the only general-purpose host; follow its public documentation rather than inferring another host or unsupported fields from older material.
Plain HTML, React, and online AI tools may not run Svelte directly. Confirm framework, dependencies, and file capabilities first. A license-permitted port within a project is different from an official runtime package for that framework. Do not claim installation or compatibility that has not been verified.
## Page layout and responsiveness
Ordinary `main`, `section`, `aside`, and `footer` elements express page semantics; use the corresponding components for navigation and controls where appropriate. Decide whether the parent or child owns padding and gaps so the layout does not duplicate spacing, radii, or shells. Outside components, use page utilities that are actually loaded. When using only the component package, use public tokens and minimal page CSS rather than assuming optional utility classes exist.
### Frame layout patterns
| Pattern | When to use it | Public entry point |
| --- | --- | --- |
| Three slots | Attachments keep their own size while content takes the remaining space | `row`; attachment `as="leading"` / `as="trailing"`; content has no attachment role |
| Single-line graphics, names and dates | Keep labels on one row and preserve attachment sizes; truncate when needed and retain full-text access | `singleLine`, attachment `as="leading/trailing"`, and `Text lines={1}` |
| First-line alignment | Align an icon with the first line of multiline text | `row firstLine`, using the same three-slot roles |
| Pin | Badges and other elements outside normal content flow | `as="pin-*"`; choose a real public position value |
Read the [Frame guide](https://snowui.dev/components/frame/reference) when you need the full composition, line-height, and layout rules. Choose singleLine for single-line labels and firstLine for prose that may wrap. Request first-line alignment explicitly; do not apply it to every horizontal container. Do not replace an existing layout capability with a fixed height, negative margin, or private page patch.
On narrow screens, adapt page arrangement, wrapping, truncation, or local scrolling to the design and content constraints. Do not keep shrinking text and functional icons. Inherited context, component size, and actual dimensions are defined by their respective public APIs; their numbers are not interchangeable.
## Color: semantics before values
Use these parameters to preserve or reproduce a SnowUI design. When an external app needs its own design values, make the smallest change through the public entry points described in the styling guide. Do not impose SnowUI-maintained tokens or utilities as a requirement on consumer projects.
Use a color Prop only when the component publicly supports it. Choose semantic values such as `Brand`, `Primary`, `Black40`, or `Background1` according to its documentation. For page colors, use the corresponding `var(--brand)`, `var(--black-40)`, or `var(--background-1)`. Black and White vary with the theme; StaticBlack and StaticWhite denote fixed black and white.
Preserve the meaning of photos and brand assets; they do not give ordinary text, backgrounds, and controls arbitrary colors. Record a Figma Style or Variable name together with its mode and theme. Do not treat a sampled screenshot color or light-mode HEX as the sole token value. Use the Figma guide for names and the [token directory](https://snowui.dev/components/design-tokens) for declarations and conditions.
## Geometry and typography tokens
| Goal | Token family | Rule |
| --- | --- | --- |
| Font size and line height | `--text-*` / `--leading-*` | Choose matching levels and keep text readable |
| Dimensions | `--size-*` | For dimensions, not font size or a component’s logical size |
| Padding | `--padding-*` | Distance between content and its shell |
| Gap | `--gap-*` | Space between neighboring elements or page regions |
| Border | `--border-*` | Border width, not spacing |
| Radius | `--radius-*` | Choose ordinary steps or a fully rounded shape by meaning |
Token numbers are not universal pixel values, and a page utility suffix need not match a token number. Read exact declarations from the CSS-generated token directory; rem values depend on the root font size. Do not copy a separate fixed-value chart or borrow from a different category merely because the computed values happen to match.
```html
Project files
```
This example shows only a page region and text. Use an existing Card, form, or overlay component when its visual or behavioral capabilities are needed.
## Where to change styles
First match the appearance with public component Props and preserve the existing look where possible. When a change is necessary, use your own class (including Tailwind already in the project), then an instance style. The full order and scope of public root, parts, child, and override entry points are in the [styling guide](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); this guide does not create another priority order. Read the target component’s `styles.md` only when customization is needed.
Do not force one radius onto every component, set unregistered internal variables, or invent parts. Component tokens and independent utilities can have different calculation paths; verify the scope of local overrides and global themes separately. Necessary source changes must retain the target version’s complete LICENSE and third-party notices, and document upgrade and framework-port boundaries.
## Checks before finishing
- Each region has a reason to use a component or ordinary semantic structure; exports and APIs match the installed version.
- Color, font size and line height, dimensions, padding, gap, border, and radius use the correct token families; explicit design differences remain visible.
- Purpose, developer count, and product scope have been checked. Restricted paid operations are not approved by plan text; a valid result may be reused within the same task.
- Check structure, content, layout, padding ownership, alignment, long text, narrow screens, light and dark themes, and necessary states in the real page. Then check keyboard and accessibility behavior.
A code check or screenshot alone cannot prove hidden interactions, every responsive scenario, or license scope. Read the relevant component’s API, types, reference, styles, or a few examples when evidence is missing; do not load the whole source library by default.
## Figma Community and design resources
[Get SnowUI Design System on Figma Community](https://www.figma.com/community/file/1388431032861751537), then read the [public component and variable map](https://snowui.dev/llms/en/figma-map.md) or [resource relationships](https://snowui.dev/llms/en/design-system-resources.md) as needed. The Community resource, public component reference file, and order-specific paid delivery are separate. Provide your own copy URL and relocate by page or collection, name, type, mode, and current value; verify node IDs in that copy even when they happen to match the reference file.