Personio Design System Plugin

Personio design system knowledge for Claude Code: foundational skills that auto-load when you're working with components, plus access to the design MCP server for live token and component data.

Install

/plugin install personio-design-system@personio-claude-code-marketplace

What does this plugin do?

MCP Server

Connects to @personio/mcp-design for live data — color palettes, component list, translation glossary — so Claude can answer "what colors are available?" or "what components exist?" without stale snapshots.

Skills (14)

Background knowledge that auto-loads when relevant. Each skill ships with trigger + output evals.

ds-color

Semantic color tokens, scales, and dark mode.

What you need: working on a component's colors, backgrounds, borders, or text.

Quick Start: Just write or edit color-related SCSS — the skill auto-loads and ensures you use tokens.$colors-static-bg-primary instead of hex codes.

Example: "Add a red warning border to this input" → Claude uses tokens.$colors-solid-bg-negative-strong-default (or the appropriate interactive variant) instead of a raw #d93025.

Why would you want this?

• Dark mode works for free — semantic tokens remap automatically
• Consistency across the product — no more near-duplicate reds or grays
• Brand accent changes cascade through the UI without code edits

ds-a11y

WCAG 2.2 AA guidance, axe-core test assertions, ARIA patterns, and Lighthouse targets.

What you need: writing or reviewing a component, especially tests.

Quick Start: Ask Claude to write a component test — it will include assertNoA11yViolations from @personio-web/design-system-utils-testing by default.

Example: "Add unit tests for <PayslipCard />" → Claude scaffolds renderWithWrapper, includes await assertNoA11yViolations(container), and remembers to swap useFakeTimers for useRealTimers before the axe call.

Why would you want this?

• Accessibility violations caught in CI, not after ship
• ARIA patterns applied correctly (listbox, combobox, dialog)
• Target Lighthouse accessibility score >90 without trial and error

ds-typography

Global typography classnames instead of direct font tokens.

What you need: adding or restyling text in a component.

Quick Start: Ask for a heading or body text — Claude applies the right heading-XL/body-M classname instead of composing font-size + weight + line-height manually.

Example: "Style this as a section header" → Claude applies heading-L rather than font-size: 24px; font-weight: 600; line-height: 1.25;.

Why would you want this?

• Typography stays coherent across products
• No one reaches for the raw tokens and drifts from the scale
• Future font changes ship through classnames, not every call site

ds-hui-deprecation

Reactive Highlight UI → DS suggestion. Auto-loads when you're editing a file that imports @highlight-ui/* for an unrelated reason — surfaces the DS equivalent, points at the per-component migration doc, and asks before migrating during drive-by work.

What you need: editing a file in personio-web that touches HUI for something other than a deliberate migration sweep.

Quick Start: Just edit a file with @highlight-ui/button (or any HUI package) — the skill auto-loads, points you at product-areas/design-system/COMPONENT-MAP.md plus the per-component file under docs/migration/, and produces a single-file plan before changing anything.

Example: "Migrate this <Button variant=\"plain\" tone=\"critical\" block className=\"mt-md\" /> to the DS" → Claude swaps the import to designSystem/components/button, remaps variant="plain" → variant="ghost", tone="critical" → destructive={true}, block → fullWidth, removes className (replacing it with a layout primitive), and points at migration/button.md.

For module-wide sweeps, visual-section planning, or feature-flag-gated rollouts → ds-plan-hui-migration instead.

ds-plan-hui-migration

Proactive HUI → DS module migration with plan-first workflow. Auto-loads on prompts like "migrate the ATS module from HUI to DS" or "sweep recruiting HUI usage", and is also slash-callable as /ds-plan-hui-migration <path>.

What you need: migrating an entire module, directory, or product area from @highlight-ui/* to the DS, OR deciding whether a particular swap needs a feature flag. Designed for a designer-facing audience — plain language, no raw build/git output.

Quick Start: Ask "sweep product-areas/recruiting for HUI imports and produce a migration plan." Optionally share a Figma link or Quality Catcher comments for precision. The skill probes its integrations (design-quality / Jira / Figma — all optional, none blocking), scans, and produces a plan grouped by visual section (wrapper → page → tabs → modals), with each component tagged ✅ Direct / ⚠️ Partial / 🔴 Action Item and each section mapping to one PR. It asks for approval at every gate and — per component meeting the criteria — ASKS whether a feature flag is needed. It does not assume a flag is always needed.

Example (no flag): "Plan a sweep for product-areas/billing — 12 Button files, simple swaps." → Claude groups them by visual section, marks them ✅ Direct, runs pnpm nx type-check + tests per section, and does not wrap any in useFeatureFlag.

Example (flag-gated): "Migrate the employee-profile drawer from @highlight-ui/drawer to a DS PageModal — high-traffic surface." → Claude recommends a feature flag (modality change + high traffic), shows the useFeatureFlag + lazy-import wiring, points the engineer at the Harness UI for flag creation plus pnpm run fetch-flags to sync types — flag creation is a manual step. Cleanup defers to team-eo-emp:remove-flag once the flag hits 100%.

Why would you want this?

• Plans by visual section, not complexity — each PR leaves a complete, shippable part of the UI migrated, so reviewers see a coherent unit instead of a random slice of one component type
• Design inputs drive the plan: a Figma link (target state) or Quality Catcher comments (element-level intent) resolve ⚠️ Partial decisions before review; the design-quality MCP supplies blast radius and the Jira ticket
• Jira automation — moves the ticket to In Progress on plan approval and In Review when the first PR goes green
• PRs open as draft and are monitored to green autonomously (CI + cubic review + comments) before being marked ready — no prompting needed between draft and ready. Heavy scans, large-section edits, and monitoring passes fan out as background workflows when available, and optional one-line /goal//loop hand-offs cover session-level waits (review babysitting, live Quality Catcher comment pickups during the prod-injection preview)
• Feature-flag posture is a decision per candidate (with a >15-import escalation), not a default — guards against over-eager FF wrapping
• Authoritative prop tables stay in personio-web (docs/migration/<component>.md) — the skill points at them so guidance never drifts

ds-locate-hui

Read-only lookup: where do HUI components actually render in the product? Auto-loads on prompts like "where do I see the HUI Drawer in the UI" or "which screens use @highlight-ui/tag", and is also slash-callable as /ds-locate-hui <component|package|module|route>.

What you need: a HUI component name, a @highlight-ui/* package, a consuming module, a dependency list (e.g. from package.json), or a route — and the wish to see the usage in the running product before deciding anything. personio-web only.

Quick Start: Ask "show me how to reach the HUI components in apps/employee-salary-tab's dependencies." The skill queries the design-quality MCP (hui_get_module, hui_route_modules, route data) and returns one block per screen: the URL (https://<your-company>.app.personio.com/salary/employee-salary/<employee-id>), the click path ("Employees → employee → Salary tab"), the HUI components to look for, the dependency chain that puts them there ("page → employee-salary-tab → garnishments widget"), and the owning team — with data freshness stated.

Example: "Why does working-schedules-common show up as a HUI dependency on the salary screen?" → Claude resolves the route, runs hui_route_modules, and explains the transitive chain (compensation profile → dashboard widgets → working-schedules) so the user knows it's not their import — and who owns it.

Why would you want this?

• Turns a dependency list into screens you can open — URL, click path, and what to look for, instead of file paths
• Dependency chains explain the "why" — transitive HUI usage is attributed to the module and team that own it
• Read-only by design: it locates and explains, then hands off to ds-plan-hui-migration / ds-hui-deprecation when you're ready to act
• Falls back to grep + the pages-router convention when the design-quality MCP is unreachable, and says exactly what precision is lost

Other skills (auto-load on relevant tasks)

ds-motion, ds-responsive, ds-spacing, ds-composition, ds-styling, ds-icons, ds-page-architecture — each follows the same pattern: boundary-triggered background knowledge that applies the canonical Personio DS approach.

Companion MCP server: design-quality

The plugin ships with a second MCP server, design-quality, declared in .mcp.json and pointed at https://eqp-api.dev.personio-internal.de/mcp. It exposes hui_* tools backed by the Experience Quality Program's HUI deprecation database — route ownership, blast radius (routes-impacted per module), per-route HUI co-imports, and migration reports.

Both ds-hui-deprecation (co-imports in the route under edit) and ds-plan-hui-migration (data-driven scoping, blast-radius tiering, ownership lookup) prefer these tools when reachable.

Reachability is environment-dependent: the URL is on personio-internal.de, so you need to be on the corporate network or VPN. If the server is unreachable, the skills fall back cleanly to filesystem grep and the per-component docs in personio-web — no degraded UX, just less precision.

Roadmap

Additional skills (form controls, modality, navigation, performance) and autonomous agents (component builder, prototype-to-prod) are being introduced in stacked follow-up PRs so they can be reviewed and evaluated independently.