pimcore/pimcore-studio-ui-ux-design-guidelines

What This Skill Covers

• Core design principles: consistency, accessibility, scalability, efficiency
• Three-panel layout system and 12-column grid
• 4px baseline spacing token system and typography
• Semantic color tokens and status indicator conventions
• Action label conventions (Add, New, Delete, Remove)
• Writing style: Title case vs Sentence case, verb-first wording, i18n requirement
• Destructive action confirmation requirement
• Loading, empty, and error state conventions
• Toolbar layout convention (left/right placement)
• Modal sizing rules and panel section themes
• Theme/dark mode readiness and styling method

When to Use This Skill

Use this when:

• Building a new widget, editor tab, or extension panel
• Adding buttons, labels, or action controls to any UI
• Choosing spacing, color, or typography values for a component
• Writing any user-facing label, title, or action text
• Positioning content within the three-panel layout
• Reviewing a component for consistency with Studio UI conventions

---

Design Principles

These five principles govern every UI decision in Pimcore Studio.

| Principle | Core idea | |---|---| | Consistency | Shared visual vocabulary — colors, typography, spacing, iconography, and interaction patterns are uniform across all modules. | | Accessibility | Keyboard navigation, semantic HTML, ARIA attributes, and high-contrast colors (exceeding WCAG thresholds) are requirements, not extras. | | Scalability | The platform must support third-party extensions, custom branding, and widget integrations without breaking existing patterns. Build modular. | | Efficiency | Predictable, inclusive interfaces let users work faster. Reusable patterns let developers build faster. Efficiency is the result of the other principles. | | Predictability | Repeat patterns across contexts. Once a user learns an interaction in one place, it must work identically everywhere else. |

---

Layout

Pimcore Studio uses a three-panel layout:

┌──────────────┬─────────────────────────────┬──────────────┐
│  Left Panel  │       Content Area          │ Right Panel  │
│  (widgets)   │  12-column responsive grid  │  (widgets)   │
└──────────────┴─────────────────────────────┴──────────────┘

Rules:

• Left and right panels: fixed default width, flex as needed; gutters are always fixed
• Content area: structured on a 12-column responsive grid; treated as individual boxes aligned to the grid
• Bottom widgets / detached tabs: can be expanded for multitasking views

Extension placement:

• New widgets → left or right panels — never inject into the content area unless it is a dedicated editor tab
• Editor tabs / content panels → content area using the 12-column grid
• Bottom panels → secondary/supporting views (logs, previews, output), not primary actions

---

Spacing

All spacing values come from the named token set — never use arbitrary pixel values.

| Token | Value | Typical use | |---|---|---| | none | 0px | Resets | | mini | 4px | Tight internal gaps (icon–label) | | extra-small | 8px | Compact component padding | | small | 12px | Table cells, tag groups, form item gaps | | normal | 16px | Default content padding | | medium | 20px | Section padding | | large | 24px | Section separation | | extra-large | 32px | Major layout gaps | | maxi | 48px | Panel separation, page-level breathing room |

Use Box, Content, Space, or Flex components to apply these tokens — see pimcore-studio-ui-layout-components. Global utility classes (.p-small, .m-y-large, etc.) are available but prefer component props.

---

Typography

• Font family: Lato, sans-serif — the only permitted font; never override fontFamily in component styles
• Base font size: 12px (token.fontSize)
• Heading 1: 35px (token.fontSizeHeading1)
• Always use token.fontSize* / token.fontSizeHeading* — never hardcode font sizes

---

Semantic Color Tokens

Use semantic tokens for all color decisions. Never pick a hex value manually.

| Role | Token | Value | Use | |---|---|---|---| | Primary / brand | colorPrimary | #722ed1 purple | Brand actions, active states | | Accent | colorAccent / colorBorderActiveTab | #13C2C2 / #00bab3 teal | Active tab border, secondary highlights | | Success | colorSuccess | #52c41a green | Confirmations, publish success | | Warning | colorWarning | #faad14 amber | Caution states | | Error | colorError | #ff4d4f red | Destructive actions emphasis, validation errors | | Info | colorInfo | maps to primary purple | Informational alerts |

For element/icon type color coding (50+ colorCoding* tokens — Red, Beige, Gold, Orange, Green, Mint, Blue, Purple, Violet, Magenta families), see pimcore-studio-ui-icons.

---

Status Indicators

Always pair color with an icon or text label — never rely on color alone.

| Status | Tag color | Icon | |---|---|---| | Published | geekblue | — | | Unpublished / Draft | gold | eye-off | | Success feedback | colorSuccess bg | checkmark | | Error / destructive | colorError | trash or close |

Use ElementTag for element status — it applies these conventions automatically.

---

Action Labels

Use the exact label that matches the semantic of the action.

| Label | Meaning | Icon | Emphasis | |---|---|---|---| | Add | Insert something that already exists into a container | Magnifying glass | — | | New | Create something from scratch | Plus (icon-only contexts only) | — | | Delete | Permanently erase from the system | Trash | Red / danger | | Remove | Remove from current UI/context only — data stays in backend | Close/X | — |

"Clear," "Remove," and "Close" intentionally share the same icon — do not add a second icon to distinguish them.

Delete is always the last item in context menus (highest priority number, e.g. 800).

---

Destructive Action Confirmation

Every action that permanently deletes or irreversibly modifies data must show a confirmation before execution. Three mechanisms exist — choose based on context:

| Mechanism | When to use | |---|---| | modal.confirm() via useStudioModal() | Standard delete confirmations — works across detached tab iframes | | useFormModal().confirm() | When the user may want a "don't ask again" option | | <Popconfirm> | Lightweight inline confirmation close to the trigger element |

Never execute a Delete action silently. Always include translated title, content (with item name), okText, and cancelText.

---

Writing Style

Title Case — Navigation and Structural Labels

Use Title Case for: menu items, tab titles, context menu entries, section headings, panel titles.

Examples: Custom Reports, Output Channels, Asset Management

Sentence case — Actions and Interactive Elements

Use Sentence case for: button labels, modal titles, inline actions, any element with a verb.

Examples: Save draft, Merge version, Export CSV

Verb-first, Action-oriented Wording

All actionable labels must start with a verb:

| ❌ Don't | ✅ Do | |---|---| | CSV Export | Export CSV | | Asset Upload | Upload asset | | Template deletion | Delete template | | Configuration reset | Reset configuration |

Rule: button / menu / control → Sentence case, verb-first. Heading / title → Title case.

i18n Requirement

All user-facing strings must go through t() from useTranslation() (react-i18next). No hardcoded English strings in components — every label, placeholder, tooltip, and error message must have a translation key.

---

Toolbar Layout Convention

Toolbars use justify='space-between' by default, creating a natural left/right split.

| Side | Content | |---|---| | Left | Filters, search inputs, navigation, breadcrumbs | | Right | Primary actions (Save, Apply, Confirm), secondary actions |

Position and theme rules:

• position='top': Filter bars, search bars at the top of a panel
• position='bottom': Action bars with save/cancel at the bottom (default)
• position='content': Toolbars between two content sections (adds borders on both sides)
• theme='primary': Main toolbars (lavender #F5F3FA background)
• theme='secondary': Neutral/white-background toolbars (secondary emphasis)

---

Loading, Empty, and Error States

Apply these states through the Content component — not custom DIVs with spinners.

| State | How to apply | When | |---|---|---| | Loading | <Content loading> | Data is being fetched; hides children until ready | | Empty | <Content none noneOptions={{ text: t('...') }}> | No data to display | | Error toast | useMessage().error(t('...')) | Non-blocking operation failure | | Error modal | useAlertModal().error(...) | Blocking error requiring user acknowledgment |

Priority order inside Content: loading → none → children. See pimcore-studio-ui-layout-components for the full Content API.

---

Modal Sizing

Always use a predefined modal size — never set an arbitrary width.

| Size key | Width | |---|---| | M | 530px | | L | 700px | | ML | 872px | | XL | 1000px | | XXL | max 1200px / 85vw |

---

Panel and Section Theming

Collapsible sections use BaseView / CollapseItem with named themes. Choose by visual hierarchy:

| Theme | Visual | Use for | |---|---|---| | card-with-highlight | White bg + primary-colored top separator | Default — most sections | | fieldset | Light bg + left 3px accent border | Grouped form fields | | border-highlight | White bg + left 3px neutral border | Sub-sections within a fieldset | | default | White bg, optional border | Plain grouping without emphasis | | success / error | Semantic green / red bg + border | Validation results, status panels |

---

Styling and Theme Readiness

• All component styles use createStyles from antd-style — never inline styles or raw CSS files
• Access theme tokens via the token argument in createStyles(({ token, css }) => ({...}))
• Never hardcode hex colors, font sizes, or spacing pixels — always reference tokens
• Both light (studio-default-light) and dark (studio-default-dark) themes are active; dark extends light — components built with tokens adapt automatically
• See pimcore-studio-ui-react-components for the full createStyles pattern

---

Accessibility Checklist

Every new component must satisfy:

• [ ] Fully operable via keyboard (Tab, Enter, Escape, arrow keys where applicable)
• [ ] Uses semantic HTML elements (<button>, <nav>, <dialog>, etc.)
• [ ] ARIA roles and labels on non-semantic interactive elements
• [ ] Color contrast meets or exceeds WCAG AA (aim for AAA)
• [ ] No information conveyed by color alone — pair with icon or label
• [ ] Focus states are visible and styled (do not suppress :focus-visible)
• [ ] All strings are translatable via t()

---

Common Mistakes to Avoid

❌ Using "Delete" for a UI-only removal

// "Delete widget" — but the widget data still exists in the backend

✅ Use "Remove" for non-destructive UI-only actions: "Remove widget"

---

❌ Executing a Delete without confirmation

// onClick={() => deleteAsset(id)}  ← no confirmation

✅ Always confirm first via modal.confirm() or <Popconfirm>

---

❌ Mixing Title case and Sentence case on buttons

"Save Draft"     ← Title case on an action button
"merge version"  ← No capitalisation

✅ Sentence case on all action buttons: "Save draft", "Merge version"

---

❌ Noun-first action labels

"CSV Export", "Asset Upload", "Property Edit"

✅ Verb-first: "Export CSV", "Upload asset", "Edit property"

---

❌ Hardcoded user-facing strings

<Button>Save draft</Button>

✅ All strings through t():

<Button>{t('asset.save-draft')}</Button>

---

❌ Arbitrary spacing or color values

style={{ padding: '14px 18px', color: '#722ed1' }}

✅ Use spacing tokens via Box/Content props, and color tokens via createStyles:

// In createStyles: color: token.colorPrimary
// In JSX: <Box padding={{ x: 'normal', y: 'small' }}>

---

❌ Custom loading spinner instead of Content state

{isLoading && <Spin />}
{!isLoading && data && <List />}

✅ Use Content loading state:

<Content loading={isLoading}>
  <List data={data} />
</Content>

---

❌ Placing a widget in the content area

// "Quick Stats" widget rendered inside the main editor content area

✅ Register as a left/right panel widget via WidgetManager

---

Next Steps

• pimcore-studio-ui-buttons — Button API matching the action label conventions above
• pimcore-studio-ui-icons — Icon usage and the colorCoding token system
• pimcore-studio-ui-layout-components — Content, Box, Flex, Space implementing the spacing tokens
• pimcore-studio-ui-widgets — Registering widgets into the correct panel areas
• pimcore-studio-ui-react-components — Component structure and createStyles CSS-in-JS pattern
• pimcore-studio-ui-modals — Modal component API and the useStudioModal / useFormModal hooks