raft-ui

--- name: display description: "Typography and display: the Text family, InlineCode vs CopyableCode vs CodeBlock, Markdown parts, DescriptionList, Avatar, FilePreview vs Files, Kbd, icons." --- # Text and display ## Contents - Use typography primitives for styled text - Text.Sans vs Text.Heading vs Text.Mono - InlineCode vs CopyableCode vs CodeBlock - Markdown and DescriptionList - Avatar - FilePreview vs file-list parts - Kbd - Icons - Per-component norms --- ## Use typography primitives for styled text Use the `Text` namespace when standalone copy needs raft-ui typography. Keep native text elements when their semantics and inherited styles are intentional. **Incorrect:** ```tsx <p className="text-sm text-gray-500">Last synced 2 minutes ago</p> ``` **Correct:** ```tsx <Text.Sans size="small">Last synced 2 minutes ago</Text.Sans> ``` --- ## Text.Sans vs Text.Heading vs Text.Mono | Component | For | | -------------- | ----------------------------------------------------- | | `Text.Sans` | body copy, labels, and descriptions | | `Text.Heading` | section and page headings; `level` is `1` through `6` | | `Text.Mono` | code-like values, metadata, and tabular numbers | Prefer the namespace used by the canonical compositions. The equivalent named exports `TextSans`, `TextHeading`, and `TextMono` also exist. **`Text.Sans` sizes** — `large` `body` `small` `caption`. **`Text.Mono` sizes** — `code` `meta` `eyebrow` `tabular`. Use `Text.Mono size="tabular"` for numbers that update in place — counts, timers, file sizes, and percentages. Proportional digits can change width and make the surrounding layout jitter. ```tsx <Text.Mono size="tabular">{unreadCount}</Text.Mono> ``` Use `size="meta"` for timestamps and IDs, `size="eyebrow"` for the small label above a section. `Text.Heading` `level` selects both the heading element and its recipe size. Pick it from document structure. Use `render` only when the surrounding document requires a different element. --- ## InlineCode vs CopyableCode vs CodeBlock | | Use | | -------------- | ------------------------------------------------------- | | `InlineCode` | a token inside a sentence — a prop name, a flag, a key | | `CopyableCode` | a single-line command the user is meant to run or paste | | `CodeBlock` | multi-line code on display | If the user's next move is to select the text, it should have been `CopyableCode` or `CodeBlock`. ```tsx <CopyableCodeRoot> <CopyableCode truncate>{command}</CopyableCode> <CopyableCodeAction aria-label="Copy install command" /> </CopyableCodeRoot> ``` `CopyableCodeRoot` sizes are `sm` and `md`. Use `truncate` on `CopyableCode` for long single-line commands, and give `CopyableCodeAction` an `aria-label` that says what is being copied. When you omit it, the label swaps between `Copy code` and `Copied code`. Compose a titled block with `CodeBlockHeader`, `CodeBlockTitle`, `CodeBlockActions`, and `CodeBlockAction` above `CodeBlockBody`. In a block without a header, place `CodeBlockActions` inside `CodeBlockBody`. Render the complete `<pre><code>…</code></pre>` as body content. --- ## Markdown and DescriptionList Rendered markdown is styled by the `Markdown*` part set. Map paragraphs, headings, lists, links, blockquotes, code, tables, images, task checkboxes, rules, and marks to the matching exported parts. Wrap wide tables in `MarkdownTableScroll`, and compose `MarkdownTable`, `MarkdownTableRow`, `MarkdownHeaderCell`, and `MarkdownCell`. `DescriptionList` renders term/value pairs. Wrap `DescriptionTerm` and `DescriptionDetails` in `DescriptionItem`, and set `direction="horizontal"` or `direction="vertical"`. --- ## Avatar ```tsx <Avatar type="human" size="sm"> <AvatarImage src={user.avatarUrl} /> <AvatarFallback>{initials}</AvatarFallback> </Avatar> ``` - Pass the required `type` and `size` props. **`type` is `agent` or `human`** and changes the treatment. - Sizes are `3xs` `2xs` `xs` `sm` `md` `lg` `xl`. - Include `AvatarFallback` whenever you include `AvatarImage`. When `Avatar` has no children, it renders its built-in fallback automatically. - Use `AvatarGroup` and `AvatarGroupCount` for stacks. Pass the required avatar `size` to `AvatarGroupCount`. - `AvatarBadge` for a presence dot attached to the avatar. For a standalone state dot elsewhere, use `Status`. --- ## FilePreview vs file-list parts `FilePreview` renders **one** file as a tile. It has dedicated shapes rather than a type prop: | Shape | For | | --------------------- | ------------------ | | `FilePreviewMedia` | images and video | | `FilePreviewDocument` | PDFs and documents | | `FilePreviewCode` | source files | | `FilePreviewFile` | anything else | Pick the shape by what the file is. `FilePreviewBadge` labels the format. The file-list parts render a **list** surface: `FilesPanel`, `FilesViewport`, `FilesList`, and per-row `FileRow`, `FileThumbnail`, `FileContent`, `FileName`, `FileMeta`, `FileMetaItem`, `FileActions`, `FileAction`, `FileRowOpen`, `FileImage`. There is no `Files` root component. Use `FilePreview` for attachments inside a composer or message; compose the file-list parts for a browsable list. --- ## Kbd ```tsx <KbdGroup aria-label="Command K"> <Kbd>⌘</Kbd> <Kbd>K</Kbd> </KbdGroup> ``` Render one key per `Kbd`. Use `KbdGroup` to apply spacing to a key combination. Add any visible separator as explicit content when the shortcut notation requires one. Inside menus, use `DropdownMenuShortcut` / `ContextMenuShortcut` instead of `Kbd`; they handle the right alignment within the row. --- ## Icons Raft-ui's internal recipes and canonical compositions are tuned to Lucide SVGs, but raft-ui does not re-export icons. When application code imports Lucide icons, declare `lucide-react` as a direct application dependency rather than relying on raft-ui's transitive dependency. A consumer may provide another SVG icon set when it preserves the component's expected sizing and stroke treatment. Let raft-ui components own their icons' default treatment. Buttons, menu items, sidebar items, toasts, and tabs apply recipe-specific sizing and sometimes theme-specific stroke widths. Override those values only when the component's API or a deliberate one-off treatment requires it. **Incorrect:** ```tsx <Button size="icon-sm"> <SearchIcon className="size-4 stroke-2" /> </Button> ``` **Correct:** ```tsx <Button size="icon-sm"> <SearchIcon /> </Button> ``` In your own markup — outside any icon-owning component — size icons explicitly (`className="size-4"`). --- ## Per-component norms **`Separator`** — use it when a divider needs raft-ui's themed visual contract or orientation behavior. Native `<hr>` remains valid when its semantics and inherited styling are intentional; avoid imitating `Separator` with an ad hoc border div. **`ScrollArea`** — use when you need styled scrollbars or a scroll region inside a panel. Compose `ScrollAreaViewport` + `ScrollAreaContent` + `ScrollAreaScrollbar` + `ScrollAreaThumb`, and `ScrollAreaCorner` when both axes scroll. Plain `overflow-auto` is fine for full-page scroll; `ScrollArea` is for bounded regions. **`Badge`** and **`Status`** — see [feedback.md](./feedback.md).