# Design guidelines
Complete typography, spacing, surface, and interaction rules with recommended and avoid examples for every rule.
Page: https://sui.draco.dev/docs/design-guidelines
Apply all of these rules when composing application interfaces with SUI. Every rule includes a working visual comparison and copyable code. Styles in the avoid column are teaching examples and should not be used in product interfaces.
## Shared styles and semantic colors
Import `@workspace/ui/globals.css` and compose components from `@workspace/ui/components/*`. Style native text elements with Tailwind size and weight utilities. Use semantic tokens such as `bg-background`, `bg-card`, `text-foreground`, `text-muted-foreground`, `bg-primary`, `border-border`, and `ring-ring`; keep destructive actions on their independent `destructive` tokens.
The default appearance uses Apple-inspired neutral surfaces and a blue accent. Select shared palettes with `data-color`: `default`, `bamboo`, `mauve`, `mist`, `sand`, `pine`, or `rose`. Remove the attribute or select `default` to reset the appearance; use `dark` for dark mode. Accent, focus, and chart colors change together while backgrounds and body text remain neutral. See [Theming](/docs/theming) for configuration.
```css
@import "@workspace/ui/globals.css";
```
```html
```
## Use 14px for content text
All content text—body, buttons, data, other interactables—must be 14px in size. 16px and above are restricted to headings and subheadings.
### Example: design-guidelines-content-text-size
```tsx
import { DesignComparison } from "../design-guidelines-comparison";
import type { ExampleProps } from "../types";
function RecommendedSample({ locale }: ExampleProps) {
const zh = locale === "zh-CN";
return
;
```
## Always sentence case headings
Never capitalize or uppercase headings. Product names must be title-cased.
The avoid column shows both title case and an `uppercase` transformation.
### Example: design-guidelines-heading-case
```tsx
import { DesignComparison } from "../design-guidelines-comparison";
import type { ExampleProps } from "../types";
function RecommendedSample() {
return
;
```
## Never change the font’s tracking
Do not use the `tracking-*` classes to change the spacing between characters.
### Example: design-guidelines-font-tracking
```tsx
import { DesignComparison } from "../design-guidelines-comparison";
import type { ExampleProps } from "../types";
function RecommendedSample({ locale }: ExampleProps) {
const zh = locale === "zh-CN";
return (
;
```
## Never use font-bold
Use `font-semibold` for headings and `font-medium` for bold inline text. Never use `font-bold`.
### Example: design-guidelines-font-weight
```tsx
import { DesignComparison } from "../design-guidelines-comparison";
import type { ExampleProps } from "../types";
function RecommendedSample({ locale }: ExampleProps) {
const zh = locale === "zh-CN";
return (
<>
required
;
```
## Put related text closer together
Related text should have smaller spacing around it than the content it belongs to.
### Example: design-guidelines-related-text-spacing
```tsx
import { Button } from "@workspace/ui/components/button";
import { DesignComparison } from "../design-guidelines-comparison";
import type { ExampleProps } from "../types";
function RecommendedSample({ locale }: ExampleProps) {
const zh = locale === "zh-CN";
return (
{zh ? "网站分析" : "Web analytics"}
{zh
? "无需修改代码即可衡量网站访问量"
: "Measure site traffic without changing your code."}
;
```
**Avoid**
```tsx
import { Button } from "@workspace/ui/components/button";
Web analytics
Measure site traffic without changing your code.
;
```
## Optically align spacing around text
Spacing around text should take into account its line height. Typically this means vertical spacing should be slightly smaller than horizontal.
### Example: design-guidelines-text-spacing
```tsx
import { Card } from "@workspace/ui/components/card";
import { DesignComparison } from "../design-guidelines-comparison";
import type { ExampleProps } from "../types";
function RecommendedSample({ locale }: ExampleProps) {
const zh = locale === "zh-CN";
return {zh ? "内容文字" : "Content text"};
}
function AvoidSample({ locale }: ExampleProps) {
const zh = locale === "zh-CN";
return {zh ? "内容文字" : "Content text"};
}
export default function Example({ locale }: ExampleProps) {
return (
}
avoid={}
/>
);
}
```
**Recommended**
```tsx
import { Card } from "@workspace/ui/components/card";
Content text;
```
**Avoid**
```tsx
import { Card } from "@workspace/ui/components/card";
Content text;
```
## Never transition colors for hover states
Color changes on hover must be immediate. Transitions on fast interactions make the UI feel sluggish.
Move the pointer between the two buttons to compare their response. SUI buttons can still transition `transform` and `box-shadow`; the hover color changes immediately.
### Example: design-guidelines-hover-color-transitions
```tsx
import { Button } from "@workspace/ui/components/button";
import { DesignComparison } from "../design-guidelines-comparison";
import type { ExampleProps } from "../types";
function RecommendedSample({ locale }: ExampleProps) {
const zh = locale === "zh-CN";
return (
);
}
function AvoidSample({ locale }: ExampleProps) {
const zh = locale === "zh-CN";
return (
);
}
export default function Example({ locale }: ExampleProps) {
return (
}
avoid={}
/>
);
}
```
**Recommended**
```tsx
import { Button } from "@workspace/ui/components/button";
;
```
**Avoid**
```tsx
import { Button } from "@workspace/ui/components/button";
;
```
## Never use borders with drop shadows
Use `ring-1 ring-border` to create a transparent border that maintains sharp edges. Do not combine `border` with a drop shadow on the same surface.
SUI Card already supplies a shadow and a subtle ring. The avoid example disables that ring to show the border-and-shadow combination explicitly.
### Example: design-guidelines-shadow-borders
```tsx
import { Card } from "@workspace/ui/components/card";
import { DesignComparison } from "../design-guidelines-comparison";
import type { ExampleProps } from "../types";
function RecommendedSample({ locale }: ExampleProps) {
const zh = locale === "zh-CN";
return (
{zh ? "内容文字" : "Content text"}
);
}
function AvoidSample({ locale }: ExampleProps) {
const zh = locale === "zh-CN";
return (
{zh ? "内容文字" : "Content text"}
);
}
export default function Example({ locale }: ExampleProps) {
return (
}
avoid={}
/>
);
}
```
**Recommended**
```tsx
import { Card } from "@workspace/ui/components/card";
Content text;
```
**Avoid**
```tsx
import { Card } from "@workspace/ui/components/card";
Content text
;
```
## Use concentric border radii
When borders or rings are 8px or less apart, their corner radii must be mathematically concentric: outer radius = inner radius + padding.
At the default SUI radius, `rounded-lg` is 10px, `rounded-xl` is 14px, and `p-1` is 4px. The radius scale uses fixed offsets: `xl` adds `0.25rem`, `2xl` adds `0.5rem`, `3xl` adds `0.75rem`, and `4xl` adds `1rem` to the base radius. Changing `--radius` preserves those gaps. `sm` and `md` subtract `0.25rem` and `0.125rem`, clamped at zero.
Pair `rounded-xl` outside with `rounded-lg` inside and `p-1`; use `rounded-2xl` outside with `p-2`. For other padding values, calculate the outer radius as the inner radius plus that padding. The scale alone does not make arbitrary combinations concentric. Change the base radius below to compare the two examples.
If the outer container uses a `border`, include its width in the distance between the two boxes. A `ring` does not occupy layout space.
### Example: design-guidelines-concentric-border-radius
```tsx
import { DesignComparison } from "../design-guidelines-comparison";
import type { ExampleProps } from "../types";
function RecommendedSample({ locale }: ExampleProps) {
const zh = locale === "zh-CN";
return (
);
}
import { Button } from "@workspace/ui/components/button";
import { type CSSProperties, useState } from "react";
```
**Recommended**
```tsx
Content text
;
```
**Avoid**
```tsx
Content text
;
```
## Align icons with the first line of text
Inline icons must be optically the same size as and be center-aligned with text. Use `h-lh flex items-center` for multi-line alignment.
The avoid column includes both a missing line-height wrapper and vertical centering against the entire paragraph. Decorative icons use `aria-hidden`; icon-only actions need an accessible name.
### Example: design-guidelines-icon-alignment
```tsx
import { InfoIcon } from "lucide-react";
import { DesignComparison } from "../design-guidelines-comparison";
import type { ExampleProps } from "../types";
function RecommendedSample({ locale }: ExampleProps) {
const zh = locale === "zh-CN";
return (
{zh
? "这段文字可能会换行，但图标仍应与第一行保持对齐"
: "Text that may wrap onto multiple lines and still align with the icon."}
Text that may wrap onto multiple lines and still align with the icon.
;
```
**Avoid**
```tsx
import { InfoIcon } from "lucide-react";
Text that may wrap onto multiple lines and still align with the icon.
;
```
```tsx
import { InfoIcon } from "lucide-react";
Text that may wrap onto multiple lines and still align with the icon.
;
```
## Reduce the font size of inline monospaced text
Monospaced text should have a slightly smaller font size (~0.9em) when mixed with regular text.
### Example: design-guidelines-inline-monospace-size
```tsx
import { DesignComparison } from "../design-guidelines-comparison";
import type { ExampleProps } from "../types";
function RecommendedSample({ locale }: ExampleProps) {
const zh = locale === "zh-CN";
return (
;
```
## Use a border to separate sticky elements
Use `border` to separate sticky elements from the content.
Scroll each column to inspect the boundary under its sticky header. A separating border is appropriate here because the header has no drop shadow.
### Example: design-guidelines-sticky-borders
```tsx
import { DesignComparison } from "../design-guidelines-comparison";
import type { ExampleProps } from "../types";
function RecommendedSample({ locale }: ExampleProps) {
const zh = locale === "zh-CN";
return (
;
```
## Maintain content size during collapse animations
Collapsible content must maintain its content size while closing to avoid its content shifting during animations.
Toggle each panel and watch the paragraph. Animate the outer wrapper from 256px to 0 while keeping the recommended inner content at `w-64`; the avoid example shrinks the text container and changes its line breaks. Reduced motion removes the transition.
### Example: design-guidelines-collapse-content-size
```tsx
"use client";
import { Button } from "@workspace/ui/components/button";
import { useReducedMotion } from "@workspace/ui/hooks/use-reduced-motion";
import { motion } from "motion/react";
import { useState } from "react";
import { DesignComparison } from "../design-guidelines-comparison";
import type { ExampleProps } from "../types";
function RecommendedSample({ locale }: ExampleProps) {
const zh = locale === "zh-CN";
const [open, setOpen] = useState(true);
const reduce = useReducedMotion();
return (
{zh
? "面板关闭时，这段文字应保持相同的换行，不要在动画过程中重新排版"
: "Text should keep the same line breaks while this panel closes."}
{zh
? "面板关闭时，这段文字应保持相同的换行，不要在动画过程中重新排版"
: "Text should keep the same line breaks while this panel closes."}
);
}
export default function Example({ locale }: ExampleProps) {
return (
}
avoid={}
/>
);
}
```
**Recommended**
```tsx
import { Button } from "@workspace/ui/components/button";
import { useReducedMotion } from "@workspace/ui/hooks/use-reduced-motion";
import { motion } from "motion/react";
import { useState } from "react";
export function RecommendedExample() {
const [open, setOpen] = useState(true);
const reduce = useReducedMotion();
return (
Text should keep the same line breaks while this panel closes.
);
}
```
**Avoid**
```tsx
import { Button } from "@workspace/ui/components/button";
import { useReducedMotion } from "@workspace/ui/hooks/use-reduced-motion";
import { motion } from "motion/react";
import { useState } from "react";
export function AvoidExample() {
const [open, setOpen] = useState(true);
const reduce = useReducedMotion();
return (
Text should keep the same line breaks while this panel closes.
);
}
```
## Never stack elevated cards
Never stack elevated cards on top of one another.
Use a plain container, spacing, or separators to group content inside a card. The recommended heading sits outside the elevated surface.
### Example: design-guidelines-layer-card-nesting
```tsx
import { Card } from "@workspace/ui/components/card";
import { DesignComparison } from "../design-guidelines-comparison";
import type { ExampleProps } from "../types";
function RecommendedSample({ locale }: ExampleProps) {
const zh = locale === "zh-CN";
return (