Update code snippet usage with current syntax highlighting recommendation

[vpicone]

I'll defer to @carbon-design-system/developers-system on what the best modern highlighting choice should be. The website has used prism for as long as I can remember. It looks like base16 is actively maintained but not sure if it's the recommendation still? https://github.com/chriskempson/base16

[joshblack]

Honestly have no idea on this lol, in general color contrast in themes has been a big problem and we would most likely defer to high-contrast themes that are popular in VS Code.

[carmacleod]

Need to update the code-snippet usage page. Currently says:

Our code snippets are built with basic styling. We recommend using Base16 for more complex syntax highlighting. Base16 provides carefully chosen syntax highlighting and a default set of sixteen colors suitable for a wide range of applications. The theme we recommend using is Solarflare.

Possibly also the code-snippet style page (i.e. where did those colors come from?). Currently says: Syntax colors Carbon has defined a set of accessible syntax colors. View an incontext example on CodePen.

[tw15egan]

Can possibly use something like https://github.com/ericwbailey/a11y-syntax-highlighting

Not sure what a11y requirements are in regards to syntax highlighting though, wouldn't it fall under decorative styles?

Would each color just need to pass on the background it exists on top of?

[carmacleod]

@tw15egan

Can possibly use something like https://github.com/ericwbailey/a11y-syntax-highlighting

Yes, but note that the background color really matters. Eric used #2b2b2b for the a11y-dark background, but that is not the same as Carbon's Gray-90 #262626. Luckily, as it turns out, all 7 of Eric's colors do pass on Carbon Gray-90. (I didn't test Gray-100 - they are likely ok too, but if you go that route, you would want to test to be sure).

However, Eric used #fefefe for his a11y-light background, and while all 7 of his a11y-light theme colors pass on White, they don't all pass on Carbon's Gray-10 #f4f4f4 (i.e. 2 of the 7 colors fail for regular size text).

---

Not sure what a11y requirements are in regards to syntax highlighting though, wouldn't it fall under decorative styles?

They are more than decorative. They help users understand the code, particularly if they are struggling for any reason. They augment/reinforce readability regardless of cognitive capabilities. According to wikipedia's syntax highlighting page:

the presence of syntax highlighting significantly reduces the time taken for a programmer to internalise the semantics of a program

---

Would each color just need to pass on the background it exists on top of?

Yes, the colors need to pass the contrast rules on their specific background.

Note that syntax highlighting has no effect on reading the code with a screen reader. Non-semantic HTML elements like div and span are used with CSS to change the color, and/or font style, of various parts of the code. Don't use semantic HTML, like <strong> or <em> within code blocks, because those may be read by screen readers, which would make reading the code confusing.

Putting it all together, I recommend that Carbon come up with 2 sets of 7 syntax highlighting colors. The light set needs to pass on both Carbon-10 and White background; the dark set needs to pass on both Carbon-90 and Carbon-100. Maybe call them something like Carbon-syntax-light and Carbon-syntax-dark. Or use "highlight" in the name instead of "syntax". Don't use a11y in the name, because that is assumed. :)

Publish the AA regular and large text contrast ratios for each color on their respective backgrounds. (You could publish the AAA regular & large text ratios as well, but it is not necessary to pass those).

I don't know if you want to go so far as saying "we recommend using this color for comments, this one for keywords, this one for symbols, etc" - that may or may not be a good idea - the obvious plus is consistency across Carbon sites; the disadvantage is that it might be too restrictive.

[tw15egan]

@carmacleod thanks for the detailed write-up! These seem like great next steps. I think it would be great if we could come up with two themes and have them added over to the templates repo for base16.

https://github.com/chriskempson/base16-templates-source

We should be able to define a theme using Prism as well if we want to stick with that. I can help out on the dev end if someone from @carbon-design-system/design wants to define a theme 👍

[vpicone]

@tw15egan it looks like the old syntax highlighting library recommendation was removed, which was the initial cause for this issue.

The current syntax highlighting docs need some love in a big way. “We have colors, here’s a codepen” is a bit lackluster. For design, we should document the syntax colors clearly per-theme. For devs, we should give some instructions on adding it for a few common languages rather than just linking out to an example.

@aagonzales mentioned she's working on that page, should we add the above to that issue or should we open a separate one?

[tw15egan]

Happy to write some instructions once we've decided on a color palette/theme 👍 I can also pair up with a designer if needed! Here are two that I've used before, open to any alternatives as well.

Highlight.js Prism (What is being used in the CodePen example)

Would we want to add any syntax highlighting into the CodeSnippet component as well?

[aagonzales]

Would we want to add any syntax highlighting into the CodeSnippet component as well?

Yes I think that would be great.

And I can pair with you TJ. I think Jeannie has explored the color combinations in the past I can talk to her.

[ivanbachev]

Hello, as part of IBM TRIRIGA modernization we worked on an expression builder pattern/component - https://ibm.invisionapp.com/share/GCO03R22EW8#/319960037_Builder_Tools_-_Workflow_Builder_-_Expression_Builder - for which we would like to use syntax highlighting.

Few months ago I posted a question on #carbon-design-system Slack channel - https://ibm-ai-apps.slack.com/archives/C0M053VPT/p1614158951047500 - to get more information on what the syntax highlight colors should be but I don’t think we have a definitive direction on which colors to use when the code editor background is white.

I found this issue on GitHub and wanted to check if a decision has been made on what colors we should use for such cases?

[tw15egan]

@ivanbachev do you have any preferences in terms of syntax highlighting libraries mentioned in this comment?

@aagonzales has any work been done on syntax highlighting? Happy to pair up on this to figure out a solution!

[ivanbachev]

@tw15egan

We don’t have a particular preference for a syntax highlighting library - as long as the colors used match Carbon guidelines.

The expression builder will most probably be implemented using this React code editor component - https://carbon-addons-iot-react.com/?path=/story/watson-iot-cardcodeeditor--with-preloaded-content

The above example uses the Monaco code editor - https://github.com/Microsoft/monaco-editor - which supports our requirements for code autocomplete, syntax highlighting and custom language specifications.

What we are looking for are guidelines on the actual colors used for the syntax highlighting.

For now we will use the colors as shown in the React code editor example and will have a note for these to be updated when Carbon guidelines become available.

[AlanGreene]

@tw15egan @aagonzales has there been any further discussion on this? We're considering using react-syntax-highlighter in our project, it supports both highlight.js and prism styles so either would work. As @ivanbachev mentioned for his use we would also be happy just to have guidance on the colours to be used, so a discussion around specific implementation details would not delay us from adopting the correct colour palette for highlighting.