carbon-design-system / carbon-website

The website for the Carbon Design System.

Carbon Design System

This is the Carbon Design System website. It's built using the gatsby-theme-carbon with GatsbyJS.

📂 Structure

src
├── components
├── data
├── gatsby-theme-carbon
├── images
├── pages
├── styles
├── util

👩‍💻 Develop

• 🤝 Contribution guidelines

• 📚 Content and Markdown guidelines

• 🗺 Navigation guidelines

• yarn install – install dependencies

• yarn dev – start the development server

• yarn dev:clean – use this if you have cache issues

• lint:js – lint your JavaScript files

• format - run Prettier

If you need more detailed information on how to set up your machine to develop locally, please take a look at our wiki.

🚀 Build

Running the build command generates all the files and places them in the public folder.

yarn build

carbon-website's Issues

Loading overlay clarification

Surfaced in slack: https://ibm-cloudplatform.slack.com/archives/C0M053VPT/p1561481033368900

Need to investigate whether a second overlay token is needed, and clarify documentation

[docs] Generate lead art for all component/usage pages

Part of the template created in #1600 will be a lead image. These must be generated for each component usage page.

Components

• Accordion
• Breadcrumb
• Button
• Checkbox
• Code snippet
• Content switcher
• Data table
• Date picker
• Dropdown
• File uploader
• Form
• Inline loading
• Link
• List
• Loading
• Modal
• Notification
• Number input
• Overflow menu
• Pagination
• Progress indicator
• Radio button
• Search
• Select
• Slider
• Structured list
• Tabs
• Tag
• Text input
• Tile
• Toggle
• Tooltip

Add sass imports

NOTHING IS STYLED OH NO

[Icon button] Need usage guidance content and style image spec

Currently we do not explain what an icon button is or when/how to use it. We need to update the usage tab with guidance.

Also would be helpful to add a spec image for icon button, since we have them displayed for all our other buttons.

Carbon website grid tiles

Describe in detail the issue you're having.

It seems like the grid tile view is broken

Is this issue related to a specific component?

Grid tile

What browser are you working on?

Chrome

What version of the Carbon Design System are you using?

Whatevers on the carbon design system website

request: Header and spec image for Modal

Request

1. I need a header image representative of a "modal." This does not have to be any specific variant, but representing a common use case is best.
2. I need a spec image to include in an "anatomy" section. The page currently has a format section. We will be switching to/creating "anatomy" sections for component pages. The shell docs have good examples of a spec image.

Row/Column components audit

Most of the Row/Column components are off

Resolve outstanding eslint issues

1. add the following to .vscode/tasks.json

   {
     "version": "2.0.0",
     "tasks": [
       {
         "type": "npm",
         "script": "lint:js",
         "problemMatcher": "$eslint-stylish"
       }
     ]
   }

2. press cmd+shift+d and select npm: lint:js

3. resolve eslint errors in Problems tray of VSCode

Anchor link isn't working

URL

[Color page] Update content for token values on Usage tab

Need to update some content for color values and add a new token on the Usage tab of the Color page on the website.

---

Add inverse-link color token

White theme
Blue 40
6ea6ff

Gray 10 theme
Blue 40
6ea6ff

Gray 90 theme
Blue 60
0062ff

Gray 100 theme
Blue 60
0062ff
interactive-02
Light themes
Gray 80
3d3d3d

Dark themes
Gray 60
6f6f6f

---

Add inverse-hover-ui color token

White theme
Gray 80 hover
4c4c4c

Gray 10 theme
Gray 80 hover
4c4c4c

Gray 90 theme
Gray 10 hover
e5e5e5

Gray 100 theme
Gray 10 hover
e5e5e5

---

interactive-02
Light themes
Gray 80
3d3d3d

Dark themes
Gray 60
6f6f6f

---

hover primary text
Dark themes
Blue 30
97c1ff

---

highlight
Gray 10 theme
Blue 20
c9deff

Gray 90 theme
Blue 70
054ada

Gray 100 theme
Blue 80
0530ad

Fix static build

 ERROR #11328 

A page component must export a React component for it to be valid. Please make sure this file exports a React component:

/Users/vincepicone/Programming/Work/carbon-www/src/pages/components/button/_examples/react/index.js

v9 site certificate error

unable to proceed...

incorrect spacing in form example...

Spacing between for elements is 34px, but per the design spec it should be 24px

https://www.carbondesignsystem.com/components/form/code

https://www.carbondesignsystem.com/components/form/style

[docs] Create and add contextual component images

Our images for components, specifically variations, just float in space. We've been repeatedly asked for this.

Related to this proposal: #1587

Components

• Accordion
• Breadcrumb
• Button
• Checkbox
• Code snippet
• Content switcher
• Data table
• Date picker
• Dropdown
• File uploader
• Form
• Inline loading
• Link
• List
• Loading
• Modal
• Notification
• Number input
• Overflow menu
• Pagination
• Progress indicator
• Radio button
• Search
• Select
• Slider
• Structured list
• Tabs
• Tag
• Text input
• Tile
• Toggle
• Tooltip

[Contribution] Identify pain points for users

Overview

Identifying and understanding user pain points to design a better process that users will follow.

• Use these to help inform the best, most friction-free process.
• Use to validate processes after they've been documented.

The details

Five key areas identified:

1. Why?

• Why should I contribute?
• I don't have time
• Contributing requires a lot of Carbon team feedback and time
• Not seeing value in opening issues
• Benefit: Portfolio pieces

2. Logistics

• Two Github sites and accounts is a barrier
• Linking process after creating two Github accounts
• What if I don't have Sketch?
• Where should I open an issue?
• Is this already being worked on?
• Will it be a priority?

3. Understanding contribution architecture

• Confusion abounds between pattern, component, experimental
• Generic contribution versus specific
• Will it become part of core Carbon? Or part of an add-on site?
• Do I need to genericize?
• Community assets versus contributions

4. Requirements

• Open Source annual training requirement
• Understanding Open Source model
• What is needed for a full contribution, partial contribution?
• Contribution requirements aren't clear

5. Best feedback process

• Issues are frequently abandoned
• People not following up/taking next steps (process not identified, expectations not clear)
• Excessive Slack comments / Help / Feedback
• Things get lost in Slack

Include 'Danger Modal' guidance on usage Tab

Need to include guidance for Danger Modals on the Usage tab.

Right now on the usage tab we include Passive, Transactional and even Input, but no Danger. We do include Danger in the code tab.

[Inverse-link] Add token to color page (usage tab) on website

Add token to color page (usage tab) on website, it is in code now.

inverse-link
Links on high contrast moments

White theme
Blue 40 (# 6ea6ff)

Gray 10 theme
Blue 40 (# 6ea6ff)

Gray 90 theme
Blue 60 (# 0062ff)

Gray 100 theme
Blue 60 (# 0062ff)

Deprecate experimental section

Deprecate experimental section in favor or inline meta data?

[Tabs] Incorrect guidance with truncation on website

We need to remove 'Tabs' at the end of this sentence about truncation. We do allow truncation in tab titles on this page https://www.carbondesignsystem.com/patterns/overflow-content/ .

bug fix[Component Code Tab]: Code snippet not displaying

bug fix[Component Code Tab]: Code snippet not displaying

Component Code Tab pulls in a Read me file from Github, as a result, there is no copy / scroll or show more functionality on these code snippets.

• Is there a way to pull in our Carbon code snippet component in this situation?

Code snippet on Component Code tab

Correct Carbon Code snippet

[content] text-input: icons in field

Add guidelines around when/how to add icons into a text-input field.

Scenarios include:

• date picker
• show/hide password #3512
• delete
• edit/non-editable #3018

Slack convo:
https://ibm-cloudplatform.slack.com/archives/C0M053VPT/p1564420553139000

[Content] Need Code tab content for all element pages

Need Code tab content for all element pages:

• Color
• Layout
• Iconography
• Motion
• Typography

request: Getting started for OMs

Throughout the Carbon site, our content speaks to two audiences: Designers and developers. A third audience we've failed to speak to is offering managers and product owners.

Our content should address OMs, beginning with a Getting started for OMs page.

This page should include:

1. A value prop for OMs considering adopting Carbon
2. An explanation of how teams can leverage Carbon now and in the future to boost UX and product experience, as well as development efficiency.

Incorrect glossary entry

Seems the definition of run needs to be updated:

Component variant switcher

User need:

A user needs to be able to see all the available variants to a component without having to scroll through the whole page.

Proposed solution:

Collapsing all the component example windows into 1, with an added component variant switcher in the form of a list of radio buttons to allow users to switch between different variants of the component. This also shortens our component pages significantly, so we avoid the loooong scroll.

FYI @designertyler @jeanservaas coz the previous issue on Component example window got closed :D

Notification component for website

There are various places in the tutorial where it'd be nice to call out items of interest. Provide background explanations. Reference external material. Pro tips, notes, etc.

https://www.carbondesignsystem.com/tutorial/react-step-1/

Today, the best that we can do is use italics:

Would it be appropriate to use the Carbon Inline Notification component? (When it can accessibly be used on a gray 10 background.)

Or, would we make a bespoke component for the website to use?

Some explorations by @jeanservaas:

Incorrect guidelines/colors/usage documentation for $inverse-support-04

On guidelines/color/usage the documentation of $inverse-support-04 for the White and Gray 10 themes incorrectly states it uses the color token Blue 40 (#408BFC).

Blue 40 is in fact defined as #6EA6FF, the correct color token for $inverse-support-04 should be Blue 50 which is #408BFC, as specified.

Incorrect token Blue 40:

Correct token Blue 50 (as used by $interactive-04 for the White theme):

Homepage and Banner

Audit the homepage use of the MDX components and add the Video banner

move site from CF to Kubernetes

[Contribution] Map users, tasks, and contribution interactions

Overview

Capture the framework that identifies users, all contribution tasks, and methods of interaction.

Link to MURAL board: https://app.mural.co/t/ibm14/m/ibm14/1560281476326/f960d923343b785fe9b0cbdeb5725e44311913e3

The details

Identify the following in a grid:

• the users (who)
• tasks (what)
• how they are interacting/contributing

Use this to map out all the flow scenarios.

[Button Style image: fix] Need to fix redlines for button

• Need to change Primary buttons to 64px padding to the right instead of 16px.

[CLA] Design page flow and get content pass

Ref issue: https://github.com/carbon-design-system/issue-tracking/issues/9

• Design pages
• Content pass
• We have all requirements to develop

Page flow:

1. Github bot prompt with link

2. Landing page CLA

3. Branch to Form for Individual or Corporation

4. Success page after submission and link to github to get started.

Sketch file box link : https://ibm.ent.box.com/folder/66831561872

[contribution] Production guidelines (page templates for each of our pages)

Overview

As we seek to boost community contribution and interaction, high-quality documentation will be critical. The best way to ensure documentation is consistent with existing Carbon content, we need to determine our documentation production rules and provide templates for each page type.

The details

Define high-level writing and content guidelines for the Carbon website. This will resemble a style guide but pared down substantially.

We will also generate a template for the following page types:

• Component usage
• Component style
• Pattern
• Getting started

Vue Getting Started guide missing required sass installs

Detailed description

Describe in detail the issue you're having.

The guide at https://www.carbondesignsystem.com/getting-started/developers/vue only mentions @carbon/vue as a required install, but sass-loader and node-sass are also required for npm run serve to work.

Is this issue related to a specific component?

It's related to the previously mentioned guide.

What did you expect to happen? What happened instead? What would you like to see changed?

I expected npm run serve to build the Vue app right away. Instead I read through the error messages and found out I was missing two NPM packages. I'd like the getting started guide to include those packages.

What offering/product do you work on? Any pressing ship or release dates we should be aware of?

My IBM Cloud platform team uses carbon components for our UI and I'm trying to learn how to integrate Carbon into a new project.

Steps to reproduce the issue

1. Follow instructions at https://www.carbondesignsystem.com/getting-started/developers/vue
2. on npm serve error messages will appear for missing packages.

Additional information

Here are the errors I received in terminal:

Module build failed (from ./node_modules/sass-loader/lib/loader.js):
Error: Cannot find module 'node-sass'
    at Function.Module._resolveFilename (internal/modules/cjs/loader.js:636:15)
    at Function.Module._load (internal/modules/cjs/loader.js:562:25)
    at Module.require (internal/modules/cjs/loader.js:690:17)
    at require (internal/modules/cjs/helpers.js:25:18)
    at Object.sassLoader (/Users/david/Workspace/carbon/node_modules/sass-loader/lib/loader.js:46:72)

Module build failed (from ./node_modules/sass-loader/lib/loader.js):
Error: Cannot find module 'node-sass'
    at Function.Module._resolveFilename (internal/modules/cjs/loader.js:636:15)
    at Function.Module._load (internal/modules/cjs/loader.js:562:25)
    at Module.require (internal/modules/cjs/loader.js:690:17)
    at require (internal/modules/cjs/helpers.js:25:18)
    at Object.sassLoader (/Users/david/Workspace/carbon/node_modules/sass-loader/lib/loader.js:46:72

Button guidance - Usage tab - Missing Tertiary

We need to add the usage for Tertiary buttons on the usage tab for Buttons

Component code pages broken

Toast notification positioning guidance

Add additional guidance and visual that explains how the toast notification should be positioned in relation to the grid and header.

Also, include direction on when to show toast in the upper right vs. bottom right (when it could cover nav or other status when it's close to the affordance to bring back the notification)

[Contribution] Identify contribution must haves

Overview

1. Identify everything that is required for a contribution to make it through. (Full Monty)
2. Identify minimum requirements.
3. Identify partial contributions, if they exist.

The details

Full Monty contribution is as follows:

• Working code
• Design spec that includes:
  • spacing & size
  • typography tokens
  • color tokens
  • states
  • interactions
• Design symbol/asset
• Documentation

extend Component Status page

Summary

Add additional rows for desired components; add columns for 'design', 'spec'. and 'design tooling'; include calls to action for empty cells to contribute including links right to repos for contribution. Determine how and where we intend to expose add-ons on this page

Justification

Makes public component roadmap, work in progress, desired components, directs people toward a contribution model,

Desired UX and success metrics

table will display per component whether design exists, spec exists, state per framework, with direct links to the appropriate locations for things, and "get started contributing this" calls to action

Update experimental deleting pattern images

Some images on deleting pattern page are out of sync with Carbon styles and will need to be updated asap.

Icon library birthday cake experience design spec

What is the next progressive step before that will help us reach the full wedding cake experience while still meeting user needs?

• Review experience roadmap progress. What user stories can be met with the addition of icon metadata and other developments.
  https://ibm.ent.box.com/notes/434699456495

• Review Wedding cake. What steps can we take to get closer to this experience? carbon-design-system/carbon-website-archive#1094

• Final user story draft for birthday cake experience.

• Design mockup of experience.

Switch themes in component demos

Dependent on #1736, implement the theme switcher.

Could also be dependent on how we support custom properties, if we rely on runtime theming to modify the component examples instead of having to set theme class names or CSS swapping.

Add small pagination variation to pagination page

The small pagination variation needs to be added to website:

• Example + code
• Style tab content
• Usage tab content

carbon-design-system/carbon#1812

Data Table -- add guidance for sorting patterns

Summary

On the Data Table page, please include a source of recommendations for different data types that correspond to “ascending/up” and “descending/down” arrows, and perhaps even what a suggested default direction would be for said data types.

Even something simple like “A-Z = up arrow” and “newest to oldest = up arrow” (if that’s true) would be helpful.

Also adding a line for designers that sorting is not included in the code, so they probably need to define sorting behavior for their devs. (As a designer, I assumed there might be some default sorting logic already present in the code for the table, but this is not true.)

Lastly, adding more description of the tri-state-sort behavior that is currently present would be helpful for designers as well. And maybe some reasoning for this odd tri-state-sort behavior (I'd want to see a persistent arrow present for whatever column is currently sorted - to not be able to see a sorted table with no arrows). It's not super clear how the sort arrows work in the code, since the sort examples on the page aren't functional. I did not know this was how the component was written, and I assumed it was a bug when I saw the developed table in our product.

Relevant information

The Usage tab on the Data Table page has a tiny section on Sorting, which is the perfect place for the guidelines. https://www.carbondesignsystem.com/components/data-table/usage

Use "px" instead of "pt" in website documentation

The v10 guidance page on iconography uses pt in an image and the image's caption. pt font unit does not get used in product development. Replace with px.

https://next.carbondesignsystem.com/guidelines/iconography/usage

Add app icons (apple, android etc)

[Content] add sections, content for Offering Management

We currently address two constituencies: Designers and Developers. at IBM and other organizations, a third constituency has a major impact on putting feature schedules on hold to adopt carbon- Offering Management.

We need to present this constituency with the value proposition in their language, and ideally tools to help them make the case to expend project points - make the investment - to put their teams roadmap on hold for some amount of time to refactor their UIs adopting our frameworks/system.

Propose an MVP Getting Started: Offering/Product Management

Then add some boilerplate of the value props for them to use in meetings, emails, presentations; presentations they can use.

We could also use this content in outreach/roadshow directly to these communities.

[docs] Clarify toggle component labeling options

Summary

Improve the guidance for the large and small toggle options by:

• clarifying the labeling options that are available, and
• including the reasoning behind the design decision to help users make the right choice.

Page to update:
https://www.carbondesignsystem.com/components/toggle/usage

Per Slack conversation:
https://ibm-studios.slack.com/archives/C0M053VPT/p1563300070300200

[docs] Inconsistent documentation on modal design

Detailed description

There seems to be some slight disagreement on spacing between the modal header and body on this page of the website: https://www.carbondesignsystem.com/components/modal/style#structure

In the 'Structure' table of styles, the margin-bottom for the bx--modal-header class is set at 8 / 0.5.

But in each example diagram below, the space between the header and body of the modals is 16 pixels. Which is the correct spacing?

Screenshots:

Content glossary component broken

/guidelines/content/glossary is broken