# UDS Usage Best Practices — Compiled Reference > **Note:** This document is a compiled reference for AI agents and LLMs. It > contains all quick-reference tables and critical rules expanded inline. For > individual component or token details, read the corresponding > `rules/react-{name}.md` or `rules/core-{name}.md` file. --- ## Table of Contents 1. [Critical Rules](#1-critical-rules) 2. [MCP Tools](#2-mcp-tools) 3. [Component & Hook Quick Reference](#3-component--hook-quick-reference) 4. [Token Quick Reference](#4-token-quick-reference) 5. [Typography](#5-typography) 6. [Icons](#6-icons) 7. [Theme Variants](#7-theme-variants) 8. [Common Mistakes](#8-common-mistakes) 9. [Figma-to-Code Workflow](#9-figma-to-code-workflow) 10. [Post-Build Verification](#10-post-build-verification) --- ## 1. Critical Rules ### ALWAYS - Use UDS React components — never rebuild from raw HTML/CSS. - Map every design element to a UDS React component whenever possible. If no matching UDS component exists, implement a custom component using UDS design tokens primarily. - Read the component's rule file before using it in code. - For bullet lists and rich text content, primarily use the `Text` component with markdown string syntax — it automatically renders ordered lists (`1. ...`) as `BulletIndex`, unordered lists with `[c]` marker (`- [c] ...`) as `BrandCheckmark`, and plain unordered lists (`- ...`) as styled bullets. - For brand logo assets, do NOT use the `Icon` component — brand logos need exact Figma dimensions, not icon sizing. Instead, wrap a native `` tag inside a `
` container sized to match the Figma design. Import the SVG from the `brandmark` icon group and choose the Light/Dark variant matching the active color scheme. - Import core brand CSS, platform CSS, and `'@ionos-web-design-system/react/style.css'` in the **CSS entry file** (e.g., `index.css`), never in `App.tsx` or any JS/TS file. - Wrap all output in ``. - Use UDS token classes for all colors, spacing, and borders. - Use the `Text` component with `asChild` for all styled text (headings, body, inline). - Use the border double-dash convention in Tailwind v4: `border--base`, not `border-base`. - Verify icon names against `icon-names.json` before importing — NEVER guess. - Pass icon inject functions directly to `icon` props as references: `icon={plus}`. - For **dynamic/data-driven icon names** (CMS content, API responses, configurable dashboards), use `useDynamicIcon` instead of static imports. Define the barrel loader at module scope and pass the kebab-case name string. - **Distinguish `ButtonIcon` from `Button` icon-only mode.** They look similar but are different components with different sizes, tokens, and features. - Use `Button` or `Link` with `asChild` for all anchor (``) elements; apply all styling on the component itself, never on the `` child. - Use `ThemeInverter` to wrap any section/card that has a visually inverted color mode. Never manually apply dark surface colors. - Set text color only via the `color` prop on the `Text` component. - Use the `Price` component for all pricing displays. - Use `AspectRatio` for all **raster** images/media from Figma. - For vector SVG assets NOT in the UDS icon package, download the SVG from Figma and use inline SVG or ``. Do NOT wrap SVGs in `AspectRatio`. ### ButtonIcon vs Button Icon-Only — Decision Tree ``` Icon-only button detected in Figma --> 1. Check the Figma component/layer name: - "ButtonIcon" or "Button Icon" → use - "Button" with icon-only variant → use ` | `` | Use component props, not child styling | | `
` for a dark promo section | `` | Use ThemeInverter for inverted sections | | `
€6.99/mo
` | `` | Never build price displays manually | | `
` | `
` or `rounded-(--protected-container-rounded)` | Use radius tokens, never arbitrary values | | `p-space-4` or `gap-space-3` | `p-4` or `gap-3` | Space tokens are natively recognized by Tailwind v4 — no alias needed | | `gap-gap-8` for a layout gap of 64px | `gap-8` | `gap-gap-8` = `--gap-8` = 8px; `gap-8` = `--space-8` = 64px. Use space tokens for layout gaps | | `p-4` assuming 16px padding | `p-3` for 16px | UDS `p-4` = 24px (comfortable). For 16px, use `p-3`. Always look up the token table | | `` (raster photo) | `` | Use AspectRatio for raster images | | `` | `` | Use compound action utilities instead of manually wiring interaction states | | `import { notifications } from '.../icon/system'` | Read `icon-names.json` first → `import { bell } from '.../icon/system'` | Never guess icon names — verify against `icon-names.json` | | `New` (unwrapped) | `
New
` | Badge stretches to full width without a `
` wrapper | | ` Feature` (manual icon bullet) | `{"- [icon:shield] Feature"}` | Use Text icon bullet markdown — auto-resolves icons with fallback | | `