---
name: design-ui
description: "Design, implement, and critique IBM Design Language and Carbon interfaces. Use for IBM/Carbon product UI, IBM Plex, layout and typography, component or flow selection, semantic color and approved brand integration, accessibility, and interaction refinement."
---

# IBM Design Language and Carbon

Design decisions should help people understand the task, act confidently, and recover when something goes wrong. Start from the user's outcome and the actual product context.

## Scope and authority

- Use the requested workspace, product, and brand. A generic request remains generic; examples and remembered projects do not authorize changes elsewhere.
- Inspect the installed framework, Carbon packages, versions, existing styles, and applicable project guidance before implementation. Prefer the project's supported Carbon components and theme APIs.
- Use current component documentation for behavior and measurements, installed package documentation/exports for APIs, and the approved product system for its semantic brand values. Read the applicable Usage, Style, Code and Accessibility contracts with [documentation intake](references/documentation-intake.md); resolve dynamic content and stale examples rather than treating heading coverage as detail review. A preview page is not proof that an API is released.
- Label local craft advice as a heuristic. When sources disagree, identify the conflict and choose the instruction applicable to this version, component, and task. Preserve accessibility and explain material deviations.
- Treat this skill as guidance, not evidence of a passing design or working component. See [source coverage](references/source-map.json) for reviewed sources and known gaps.

## Choose the mode

**Design or build:** Read [senior workflow](references/senior-workflow.md) and the relevant component/container reference. Before coding runnable interactions, also read [practical implementation review](references/practical-implementation-review.md) and the applicable interaction contracts; use them to establish action destinations, heading/control structure, pending-state and font-delivery acceptance before implementation. Establish the main task, objects, data volume, important states, and an observable outcome to judge the result. Choose density by region: scanning zones can be compact while decision zones need space.

**Critique:** Use [taste](references/taste.md). For a task-flow, IA or multi-view audit, use the sibling [review product experience workflow](../review-product-experience/SKILL.md). Review alone does not authorize implementation or publication. Inspect the supplied screen or running interface when available. Distinguish visible evidence, source-code findings, and hypotheses; do not describe an unseen screenshot. Prioritize hierarchy and task completion, while still checking serious accessibility and functional issues. For reviews spanning pages or tabs, use the [cross-view comparison](references/taste.md#cross-view-consistency) and report coverage before giving an overall verdict.

When a composition decision benefits from a visual analogue, use one relevant [casebook study](references/visual-casebook.md) to examine visible choices and tradeoffs. Adapt its reasoning to the actual task; the examples are teaching material, not product acceptance evidence.

For a product shell header, use the [Carbon header visual benchmark](references/ui-shell.md#what-good-looks-like-header-benchmark) in both design and critique. The linked Carbon guidelines and React Storybook are the reference for its compact silhouette, identity/navigation hierarchy and contiguous utilities. Compare the actual rendered header with the relevant example; preserve approved brand authority and verify behavior separately.

For a data table, use the [Carbon data table visual benchmark](references/composition.md#what-good-looks-like-data-table-benchmark) in both design and critique. Compare the rendered table with the official Guidelines and React Basic example for column alignment, density, surfaces, separators and action placement. Read its sizing reconciliation before selecting toolbar sizes; use the relevant sibling stories for richer variants.

For search, use the [Carbon Search visual benchmark](references/forms-and-upload.md#what-good-looks-like-search-benchmark) in both design and critique. Compare the rendered field with the official Guidelines and React Search overview for field shape, icon/text alignment, clear-control space and placement. Read its version-qualified size mapping; distinguish the default, fluid and expandable treatments and verify application results separately.

For a form, use the [Carbon Form visual benchmark](references/forms-and-upload.md#what-good-looks-like-form-benchmark) in both design and critique. Compare labels, helper text, field alignment, grouping and actions with the Guidelines and Web Components Default example. Read the spacing/sizing reconciliation and preserve the consuming framework's API and submission contracts; a Web Components story does not establish React behavior.

For design and critique of these four compositions, read [release gates](references/release-gates.md) alongside the visual benchmarks. Use the geometry and keyboard checks as applicable acceptance criteria; report unrun checks as untested.

**Focused guidance:** Read only the references needed to answer the question. Explain a concrete decision and its conditions rather than prescribing an unrelated build or test sequence.

Identify the visual register: productive interfaces use efficient, predictable layout and fixed UI typography; expressive reading/arrival regions can use fluid type, imagery, and greater scale. Mix deliberately by region, with consistent component behavior. A marketing page should not acquire product shell chrome simply because Carbon is in use. An approved product brand can override generic values through semantic roles; see [color authority](references/color-and-brand.md).

## Implementation and verification

1. Use the installed component system first. The bundled CSS is an optional standalone prototype fallback, limited to White and Gray 100. Read [asset scope](references/asset-scope.md) before using it; it is not a JavaScript component library or a four-theme implementation.
2. Compose with the 2x Grid, named type styles, spacing tokens, semantic colors, and the applicable component's anatomy. Use component-specific corner, size, and focus treatments rather than global styling absolutes. Trace authored color rules to semantic roles, including interaction states; see the [worked example](references/semantic-token-example.md).
3. Use at most one page-level primary action when the task warrants it; a monitoring or read-only view may need none. Do not invent a primary to satisfy a count; a focused modal, panel, or task may have its own primary while active. Repeated sections do not each need a primary button. See [component selection](references/components-preview.md).
4. Design the relevant no-data, no-results, loading, failure, partial/overflow, submitting, and success states. For a table's no-data state, replace the empty table including headers/footer; preserve useful surrounding actions. Keep search/filter context in a no-results state. See [patterns](references/patterns.md).
5. Follow [accessibility](references/accessibility.md) for names, control states, keyboard/focus, and evidence. Disabled is not hidden. A search field still needs an accessible name when its visible label is omitted.
6. Preserve supported Carbon microinteractions. Choose motion by purpose and event semantics, keep feedback immediate, and honor reduced-motion preferences. Frequent use and keyboard input do not impose a blanket animation ban. See [motion](references/motion.md).
7. For runnable work, use [practical implementation review](references/practical-implementation-review.md) to define and test observable destinations/action outcomes, relevant async recovery, and containment through the nested layout. Check normal viewport geometry in open/expanded and feedback states at required widths, themes and directions; for code, verify ordinary Tab access and scrolling on the actual overflow owner. Confirm delivery of used font assets. Scope these checks to the affected task and installed version. Report pass/fail/untested with evidence; source wiring, a caption or a file path alone does not prove rendered behavior or image inspection. The contrast checker's presets are diagnostics, not product acceptance tests.
8. Review the result against the task and [taste rubric](references/taste.md), including [source review](references/design-engineering.md#source-review-for-authored-color). Record meaningful tradeoffs, evidence, and the next corrective action if work remains.

## Reference routing

| Reference | Use when |
|---|---|
| [Release gates](references/release-gates.md) | Design and critique of header, table, search, and form compositions; geometry and keyboard acceptance checks and evidence limits |
| [Practical implementation review](references/practical-implementation-review.md) | Runnable destinations/actions, async lifecycle and focus, code scrolling/copy, nested narrow/RTL sizing, fonts and frozen-output verification |
| [Pattern selector](references/pattern-selection.md) | Choosing between containers, feedback, loading, search, filters, control states, and deletion treatments from the task |
| [Components](references/components-preview.md), [index](references/components-preview-index.md), [coverage](references/components-preview-coverage.md) | Selecting a core component; locating its variants, specifications, accessibility, and source sections |
| [Core interaction contracts](references/core-interaction-contracts.md) | Tree view hierarchy/state/flags/keyboard; Tile variants/nesting/expansion; Tabs activation/panels/dismissal; Accordion, Breadcrumb, Button, Checkbox, Code snippet, Contained list, Content switcher and List; source conflicts and released-API limits |
| [Menus and triggers](references/menus-and-triggers.md) | Tooltip/Toggletip naming/focus/placement, command menus and Popover composition, menu/combo/overflow actions, focus/selection roles, controlled closing, placement and feature-flag/API differences |
| [Date and time](references/date-and-time.md) | Date question, locale/format/timezone, manual/calendar/range entry, validation, dismissal and responsive calendar checks |
| [Selection controls](references/selection-controls.md) | Toggle state/persistence, Tag variants, radio/native Select/dropdown/multiselect/combo-box choice, StructuredList selection, keyboard/read-only differences, mixed/clear scope and custom values |
| [Forms and upload](references/forms-and-upload.md) | Text input/textarea counters, editing and password reveal; Search scope/results/clear, Slider range/keys/callbacks, required/optional instructions, fluid help, numeric validation, uploader state and focus/recovery |
| [Action feedback and links](references/action-feedback-and-links.md) | Notifications, system progress versus user steps, loading lifecycle/announcements, callbacks/recovery, true links and navigation semantics |
| [Composition](references/composition.md) | Choosing page, modal, panel, tearsheet, table, or dashboard structure; IBM Products |
| [Patterns](references/patterns.md), [coverage](references/patterns-coverage.md) | Notifications, forms, search, filtering, loading, empty states, disclosure |
| [Framework integration](references/framework-integration.md) | Official/community setup, Web Components, legacy snippets and Carbon MCP prompt/client boundaries |
| [MCP result validation](references/mcp-result-validation.md) | Reconcile retrieved examples, chart completeness, stylesheet delivery and supplemental instruction conflicts |
| [Community flows](references/community-flows.md) | Community/core boundaries; create/edit/remove, import/export, API keys and chat |
| [Fluid styles](references/fluid-styles.md) | Fluid versus default styling, responsive width, attached actions, form help, separators and component-specific exceptions |
| [Accessibility](references/accessibility.md) | Accessible names, disabled/read-only states, keyboard, focus, and verification limits |
| [2x Grid](references/2x-grid.md) | Geometry, breakpoints, grid behaviors, guideline subcategories, or implementation |
| [Tokens](references/tokens.md), [color and brand](references/color-and-brand.md) | Semantic values, contrast traps, approved brand mappings |
| [Themes](references/themes.md) | White, Gray 10, Gray 90, Gray 100, nested layers, or user/system preferences |
| [Spacing](references/spacing.md) | Fixed token values, responsive composition, Stack/gap, component spacing |
| [Typography](references/typography.md), [typeface](references/typeface.md), [coverage](references/typeface-coverage.md) | Productive/expressive type, Plex families, multilingual text, fonts |
| [Icons and pictograms](references/icons-and-pictograms.md), [dynamic libraries](references/dynamic-svg-libraries.md) | Library symbols, sizes, foregrounds, optical alignment, clearance |
| [Motion](references/motion.md) | Productive/expressive movement, easing, duration, choreography, reduced motion |
| [Spatial workspaces](references/spatial-workspaces.md) | Maps, floor plans, inspectors, spatial keyboard navigation, and draft/publication boundaries |
| [Artifact intake](references/artifact-intake.md) | Reviewing supplied research, prototypes and mockups for selective reuse |
| [UI shell](references/ui-shell.md) | Header/side-nav/utility composition, controlled state, skip/focus/route contracts and responsive navigation |
| [Next.js shell recipe](references/nextjs-shell.md) | App Router integration with real Carbon navigation, shared routes, dismissal, and focus behavior |
| [Status and data visualization](references/status-and-dataviz.md), [chart behavior](references/chart-behavior.md), [chart example integration](references/chart-example-integration.md) | Status meaning, chart choice, domains, missing data, legends, dashboards and design-only/code boundaries |
| [Content design](references/content-design.md) | Action semantics, writing style, localization and label/behavior agreement |
| [AI explainability](references/ai-explainability.md) | AI provenance, focused/broad labels, read-only access, override/revert and keyboard behavior |
| [Documentation intake](references/documentation-intake.md) | Public category routing, four component tabs, contribution readiness/templates, dynamic documentation and source conflicts |
| [Senior workflow](references/senior-workflow.md), [taste](references/taste.md) | Screen/flow design, density, judgment, critique |
| [Visual casebook](references/visual-casebook.md) | Annotated before/after table, form, dashboard, settings and expressive composition; task-dependent tradeoffs |
| [Design engineering](references/design-engineering.md) | Browser behavior, interruption/recovery, implementation polish |
| [Carbon Next](references/carbon-next.md) | Roadmap, preview/release boundaries, flags, future versions |
| [Asset scope](references/asset-scope.md) | Optional standalone CSS fallback and its limits |
| [Source map](references/source-map.json) | Source authority, category/subcategory coverage, freshness, unresolved gaps |
| [Evaluation](references/evaluation.md), [history](references/evaluation-history.md) | Preparing, running, grading, comparing evaluations, or interpreting existing evidence |

IBM logos, photography, illustration, app icons, and creative animation are not yet fully covered by local playbooks. Follow the relevant official route in the source map and disclose that boundary; do not generalize productive UI rules to every IBM visual expression.