carbon-design-system/carbon

[Feedback]: UI Shell is way too complicated and not really documented

Open

#19,715 opened on Jun 19, 2025

View on GitHubContributor guide
 (4 comments) (1 reaction) (0 assignees)JavaScript (1,733 forks)batch import
afrohackshacktoberfestneeds: community contributionpackage: @carbon/web-componentsproposal: acceptedstatus: help wanted 👐type: enhancement 💡

Repository metrics

Stars
 (7,442 stars)
PR merge metrics
 (Avg merge 9d 14h) (106 merged PRs in 30d)

Description

The problem

Hey, just wanted to shoot you some initial impressions. I decided to use carbon at work for a new project. It looks good, the components are great.

However, every web projects starts with layout and ground work. Unfortunately Carbon makes it __ really __ hard to get something good-looking, working.

The docs are basically absent for the UI Shell. I am talking about the web components

My issues with ui-shell webcomponents are:

  • No code in docs, need to reverse engineer it.
  • Layout padding is broken and stuff gets overlayed to each other.
  • The docs dont make it clear what sub components are being used in the ui shell.
  • No alternatives, no navbar, no navbar items, no standalone sidebar. (I tried several components to use as that)

I think this is a huge missed opportunity get developers started. Especially in environments where the first impression counts. (need hours to fiddle with basics).

I hope I can get this working because I really want to use it.

The solution

Add source info and get the ui shell some love.

Examples

No response

Package

@carbon/web-components

Application/PAL

Internal

Business priority

None

Available extra resources

No response

Code of Conduct

Contributor guide

Research direction
Review the existing UI Shell components in the codebase and create documentation with usage examples.
Tech stack
javascriptweb components
Domain
frontend
Issue type
Documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Clear
Prerequisites
None
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
60