From uds-orchestrator
UDS project scaffolding, CSS configuration, and audit workflow. Use when the user asks to set up a new project with UDS, configure Tailwind v4 with UDS tokens, troubleshoot missing styles or tokens not resolving, audit an existing project for UDS configuration issues, or when mentions of UDS install, CSS imports, data-brand, data-platform, or data-color-scheme appear. Does NOT trigger on component usage or Figma-to-code — see uds-usage-best-practices.
npx claudepluginhub ionos-web-design-system/uds-orchestrator --plugin uds-orchestratorThis skill uses the workspace's default tool permissions.
Complete guide for scaffolding new UDS projects, configuring CSS/Tailwind, and
Guides Next.js Cache Components and Partial Prerendering (PPR): 'use cache' directives, cacheLife(), cacheTag(), revalidateTag() for caching, invalidation, static/dynamic optimization. Auto-activates on cacheComponents: true.
Guides building MCP servers enabling LLMs to interact with external services via tools. Covers best practices, TypeScript/Node (MCP SDK), Python (FastMCP).
Share bugs, ideas, or general feedback.
Complete guide for scaffolding new UDS projects, configuring CSS/Tailwind, and auditing existing projects for configuration issues.
rules/setup-css-imports.mdrules/setup-fonts.mdrules/setup-audit-checklist.mdrules/setup-troubleshooting.mdrules/setup-advanced.mdThe @ionos-web-design-system/* packages are published on an internal JFrog
registry, not the public npm registry. Before installing:
@ionos-web-design-system scopenpm install fails with 401, 403, or E404 errors, the registry
auth token is missing or invalidnpm install @ionos-web-design-system/react @ionos-web-design-system/core
Optional packages:
npm install @ionos-web-design-system/icon # Icons
index.css)All CSS imports go here — never in JS/TS files:
@import 'tailwindcss';
@import '@ionos-web-design-system/core/brands/ionos'; /* match your brand */
@import '@ionos-web-design-system/core/platforms/comfortable'; /* match your platform */
@import '@ionos-web-design-system/react/style.css';
Import order is critical.
@import 'tailwindcss'must come first, followed by brand CSS, platform CSS, then component styles. Seerules/setup-css-imports.mdfor all scenarios.
Set required data-* attributes on the <html> element:
<html
data-brand="ionos"
data-platform="comfortable"
data-color-scheme="light"
></html>
| Attribute | Values |
|---|---|
data-brand | ionos, strato, fasthosts, homepl, strefa, udag, world4you, arsys |
data-platform | comfortable, compact |
data-color-scheme | light, dark |
All design tokens resolve automatically based on these attributes. Change any attribute at runtime and every token updates instantly — no rebuild required.
import ThemeProvider from '@ionos-web-design-system/react/theme-provider';
export default function App() {
return (
<ThemeProvider>
<div className="text-base">
{/* All UDS components go inside ThemeProvider */}
</div>
</ThemeProvider>
);
}
Important: The
text-baseclass on the root wrapper sets the UDS base text color (--text-base). Without it, all text inherits the browser default#000black because theTextcomponent does not set a color by default.
// index.css
// @import 'tailwindcss';
// @import '@ionos-web-design-system/core/brands/ionos';
// @import '@ionos-web-design-system/core/platforms/comfortable';
// @import '@ionos-web-design-system/react/style.css';
import ThemeProvider from '@ionos-web-design-system/react/theme-provider';
import Button from '@ionos-web-design-system/react/button';
function App() {
return (
<ThemeProvider>
<div className="text-base">
<Button variant="primary" size="medium">
Get Started
</Button>
</div>
</ThemeProvider>
);
}
The correct import order in the CSS entry file is essential. Misordering causes tokens to fail silently.
@import 'tailwindcss';
@import '@ionos-web-design-system/core/brands/{brand}';
@import '@ionos-web-design-system/core/platforms/{platform}';
@import '@ionos-web-design-system/react/style.css';
For runtime theme switching during development:
@import 'tailwindcss';
@import '@ionos-web-design-system/core/brands/*';
@import '@ionos-web-design-system/core/platforms/*';
@import '@ionos-web-design-system/react/style.css';
Icons don't need CSS imports — they're SVG inject functions. Just install and import:
npm install @ionos-web-design-system/icon
For all import scenarios and edge cases, see
rules/setup-css-imports.md.
UDS brands use specific font families. The core CSS declares font-family via
tokens, but the actual font files must be loaded by the project.
| Brand | Font Family | Source |
|---|---|---|
ionos | Inter | Google Fonts / npm |
strato | Nunito Sans | Google Fonts / npm |
fasthosts | Poppins | Google Fonts / npm |
homepl | Lato | Google Fonts / npm |
strefa | Lato | Google Fonts / npm |
udag | Nunito Sans | Google Fonts / npm |
world4you | Nunito Sans | Google Fonts / npm |
arsys | Inter | Google Fonts / npm |
Add the font in index.html via Google Fonts or import locally. The UDS
font-family token will reference it automatically once loaded.
For detailed font setup instructions, see
rules/setup-fonts.md.
Before building, confirm Tailwind v4 is wired up correctly:
@import 'tailwindcss' is in the CSS entry file (index.css), not in
vite.config or main.tsx@import 'tailwindcss' — order matterstailwind.config.js unless explicitly using the v3 plugin pathborder--base (double dash) works — single dash means v4 is misconfigured@import '@ionos-web-design-system/react/style.css' is presentdata-brand, data-platform, data-color-scheme set on <html><ThemeProvider> wraps all UDS component usage in Reacttext-base class for base text color fallbackWhen auditing an existing project for UDS configuration issues:
data-brand, data-platform,
data-color-scheme#[0-9a-fA-F]), rgb(,
rgba(bg-red, text-gray,
border-blue, etc.border-base (should be
border--base in v4)text-base used as font size (should be
Text component)For the full structured checklist, see
rules/setup-audit-checklist.md.
Use Playwright MCP to verify tokens are mounting correctly at runtime:
Navigate to the running app and inspect that CSS custom properties resolve:
// Check if UDS tokens are loaded on :root / html
const brand = await page.evaluate(() =>
getComputedStyle(document.documentElement).getPropertyValue('--surface-base')
);
// If empty string, tokens are not resolving — check CSS imports
const html = await page.locator('html');
const brand = await html.getAttribute('data-brand');
const platform = await html.getAttribute('data-platform');
const colorScheme = await html.getAttribute('data-color-scheme');
// All three should be non-null
const font = await page.evaluate(
() => getComputedStyle(document.body).fontFamily
);
// Should contain the brand's font (e.g., "Inter" for ionos)
This plugin configures Playwright MCP via .mcp.json. Requirements:
npx execution)@playwright/mcpThe Figma MCP is platform-managed by Claude Code (via claude.ai Figma). It is
NOT declared in this plugin's .mcp.json.
Auth troubleshooting:
For advanced CSS optimization, Tailwind v3 plugin, and useTheme hook, see
rules/setup-advanced.md.