Design documentation for CodeEditor linting #2752

LilithJames-HDS · 2025-03-06T19:32:26Z

📌 Summary

If merged, this PR will add a section at the end of the Guidelines page for CodeEditor that describes the linting feature available to users only in the JSON language variant of the CodeEditor.

🛠️ Detailed description

Brief description added. Questions for the team:

Should there be images to allow designers to preview what the linting feature looks like?
Is this the appropriate location for this information given its niche application in the component?

🔗 External links

Jira ticket: HDS4629
Figma file: Preview of linting

vercel · 2025-03-06T19:32:30Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
hds-showcase	✅ Ready (Inspect)	Visit Preview	Mar 7, 2025 8:00pm
hds-website	✅ Ready (Inspect)	Visit Preview	Mar 7, 2025 8:00pm

majedelass

I left two bits of feedback, one non-blocking and not really necessary, while the other I think could benefit consumers (specifically designers) with how linting looks like.

website/docs/components/code-editor/partials/guidelines/guidelines.md

andgen404

I left some comments, but looking good!

andgen404 · 2025-03-06T20:35:05Z

website/docs/components/code-editor/partials/guidelines/guidelines.md

@@ -104,3 +105,6 @@ In **Figma** we provide a handful of example languages intended as visual exampl

 If you wish to create custom examples using the Code Editor, we publish all of the relevant syntax highlighting variables in the [HDS Components v2.0](https://www.figma.com/design/iweq3r2Pi8xiJfD9e6lOhF/HDS-Components-v2.0?node-id=67166-37020&t=gWdKy44MzTP4cTRo-1) library. However, due to the number of languages supported by the component, the color variables use a generic naming schema (e.g., cyan, red, purple) to remain as agnostic as possible when being applied to different languages.
 For more details around syntax, visit the [specifications](/components/code-editor?tab=specifications).
+
+## Linting (JSON language only)


Suggested change

## Linting (JSON language only)

### Linting (JSON language only)

I think it makes sense to have the content in this section. Maybe bump it down to an h3?

I don't think this should live under Language, it's its own feature like line-highlight and it happens to only be applicable to JSON. Open to moving it around if everyone disagrees with me though

This follows the setup in the showcase. It is it's own feature, but it technically won't work without language. I'm indifferent I think.

website/docs/components/code-editor/partials/guidelines/guidelines.md

jorytindall

Couple of comments around the structure here, but I do think that an image would go a long way for this feature. I also might suggest including something about this not being supported in Figma.

website/docs/components/code-editor/partials/guidelines/guidelines.md

heatherlarsen

Nice work! I left a couple of minor suggestions.

website/docs/components/code-editor/partials/guidelines/guidelines.md

heatherlarsen · 2025-03-06T22:08:33Z

website/docs/components/code-editor/partials/guidelines/guidelines.md

+The Code Editor supports "linting" (currently only of JSON code) a user's code. This feature will highlight an error with an underline and display an icon next to the line number, each of which will show a tooltip on hover. To view all alerts in the editor, users can open a dialog using Ctrl-Shift-m (Cmd-Shift-m on macOS).
+
+!!! Info 
+Linting within the Code Editor is only supported for JSON. If you require linting for addition languages [contact](/about/support) the HDS team.


I don't have strong feelings about this, but I don't feel like these details need to go in the info banner. The first sentence is also above; the second could live as a standalone below the previous paragraph.

Thanks for the notes! I updated all the suggestions and for this info banner I kept the callout that this is not supported in Figma (which we have in info banners on other components) to make it clear at a glance that this is in code only. I moved the contact support info to the end of the section as well. Let me know what you think!

It looks like maybe something got reverted because I still see the first two sentences.

website/docs/components/code-editor/partials/guidelines/guidelines.md

heatherlarsen · 2025-03-06T22:12:02Z

website/public/assets/components/code-editor/codeeditor-linting-preview-tooltip.png

This example is a little jarring in the flow of the content because the main element is on the right, while in the others, it's on the left. The left is most common in our documentation and is preferred. Could you orient this so the code editor itself is on the left?

website/docs/components/code-editor/partials/guidelines/guidelines.md

shleewhite

Looks good to me, once the spelling error in the target branch gets fixed you can just re-run the failing test and it should be good to go.

Co-authored-by: Heather Larsen <[email protected]>

…ines.md Co-authored-by: Lee White <[email protected]>

heatherlarsen

Two minor updates, then I think this is good to go.

heatherlarsen · 2025-03-07T20:07:19Z

website/docs/components/code-editor/partials/guidelines/guidelines.md

+The Code Editor supports "linting" (currently only of JSON code) a user's code. This feature will highlight an error with an underline and display an icon next to the line number, each of which will show a tooltip on hover. To view all alerts in the editor, users can open a dialog using Ctrl-Shift-m (Cmd-Shift-m on macOS).
+
+!!! Info 
+Linting within the Code Editor is only supported for JSON. If you require linting for addition languages [contact](/about/support) the HDS team.


It looks like maybe something got reverted because I still see the first two sentences.

heatherlarsen · 2025-03-07T20:10:35Z

website/docs/components/code-editor/partials/guidelines/guidelines.md

@@ -104,3 +104,24 @@ In **Figma** we provide a handful of example languages intended as visual exampl

 If you wish to create custom examples using the Code Editor, we publish all of the relevant syntax highlighting variables in the [HDS Components v2.0](https://www.figma.com/design/iweq3r2Pi8xiJfD9e6lOhF/HDS-Components-v2.0?node-id=67166-37020&t=gWdKy44MzTP4cTRo-1) library. However, due to the number of languages supported by the component, the color variables use a generic naming schema (e.g., cyan, red, purple) to remain as agnostic as possible when being applied to different languages.
 For more details around syntax, visit the [specifications](/components/code-editor?tab=specifications).
+
+## Linting
+The Code Editor supports linting for JSON using [CodeMirror6](https://codemirror.net/examples/lint/). This feature highlights all errors with an underline and an icon next to the line number. Each icon has a tooltip explaining the error on the associated line. To view all alerts in the editor, users can open a dialog using Ctrl-Shift-m (Cmd-Shift-m on macOS).


Removing the duplicative sentence.

Suggested change

The Code Editor supports linting for JSON using [CodeMirror6](https://codemirror.net/examples/lint/). This feature highlights all errors with an underline and an icon next to the line number. Each icon has a tooltip explaining the error on the associated line. To view all alerts in the editor, users can open a dialog using Ctrl-Shift-m (Cmd-Shift-m on macOS).

The Code Editor supports linting for JSON using [CodeMirror6](https://codemirror.net/examples/lint/). This feature highlights all errors with an underline and an icon next to the line number. Each icon has a tooltip explaining the error on the associated line.

LilithJames-HDS requested review from a team as code owners March 6, 2025 19:32

hashibot-hds added packages/components docs-website Content updates to the documentation website showcase labels Mar 6, 2025

LilithJames-HDS requested a review from zamoore March 6, 2025 19:32

majedelass reviewed Mar 6, 2025

View reviewed changes

website/docs/components/code-editor/partials/guidelines/guidelines.md Outdated Show resolved Hide resolved

website/docs/components/code-editor/partials/guidelines/guidelines.md Outdated Show resolved Hide resolved

andgen404 reviewed Mar 6, 2025

View reviewed changes

jorytindall reviewed Mar 6, 2025

View reviewed changes

vercel bot deployed to Preview – hds-showcase March 6, 2025 21:12 View deployment

LilithJames-HDS changed the base branch from main to zamoore/HDS-4361/CodeEditor-linting-website March 6, 2025 21:14

vercel bot deployed to Preview – hds-website March 6, 2025 21:14 View deployment

hashibot-hds removed packages/components showcase labels Mar 6, 2025

vercel bot deployed to Preview – hds-showcase March 6, 2025 21:21 View deployment

vercel bot deployed to Preview – hds-website March 6, 2025 21:23 View deployment

vercel bot deployed to Preview – hds-showcase March 6, 2025 21:29 View deployment

vercel bot deployed to Preview – hds-website March 6, 2025 21:31 View deployment

vercel bot deployed to Preview – hds-showcase March 6, 2025 21:40 View deployment

vercel bot deployed to Preview – hds-website March 6, 2025 21:42 View deployment

heatherlarsen reviewed Mar 6, 2025

View reviewed changes

vercel bot deployed to Preview – hds-showcase March 7, 2025 14:17 View deployment

vercel bot deployed to Preview – hds-website March 7, 2025 14:19 View deployment

vercel bot deployed to Preview – hds-showcase March 7, 2025 14:45 View deployment

vercel bot deployed to Preview – hds-website March 7, 2025 14:47 View deployment

vercel bot deployed to Preview – hds-showcase March 7, 2025 14:52 View deployment

vercel bot deployed to Preview – hds-website March 7, 2025 14:54 View deployment

LilithJames-HDS requested review from heatherlarsen and jorytindall March 7, 2025 14:56

LilithJames-HDS requested a review from andgen404 March 7, 2025 14:57

shleewhite reviewed Mar 7, 2025

View reviewed changes

vercel bot deployed to Preview – hds-showcase March 7, 2025 16:14 View deployment

vercel bot deployed to Preview – hds-website March 7, 2025 16:18 View deployment

shleewhite reviewed Mar 7, 2025

View reviewed changes

website/docs/components/code-editor/partials/guidelines/guidelines.md Outdated Show resolved Hide resolved

vercel bot deployed to Preview – hds-showcase March 7, 2025 16:39 View deployment

vercel bot deployed to Preview – hds-website March 7, 2025 16:42 View deployment

shleewhite approved these changes Mar 7, 2025

View reviewed changes

zamoore force-pushed the zamoore/HDS-4361/CodeEditor-linting-website branch from c1811e4 to 0f49b5b Compare March 7, 2025 19:54

zamoore and others added 15 commits March 7, 2025 14:55

working on the json linter

f36f6c3

Update guidelines.md

362f14f

Update to add images and tweak copy

e99fd91

Updates to image quality and accepting comment edits

83ef333

Troubleshooting images

6baf316

Addition of callout

cecd93d

Update to image and info callout

23678fd

Apply suggestions from code review

f2cd828

Co-authored-by: Heather Larsen <[email protected]>

Adding links to CodeMirror and support

be0bd8b

Update website/docs/components/code-editor/partials/guidelines/guidel…

0398b80

…ines.md Co-authored-by: Lee White <[email protected]>

Update website/docs/components/code-editor/partials/guidelines/guidel…

a119115

…ines.md Co-authored-by: Lee White <[email protected]>

Update website/docs/components/code-editor/partials/guidelines/guidel…

f312bcf

…ines.md Co-authored-by: Lee White <[email protected]>

Update website/docs/components/code-editor/partials/guidelines/guidel…

2b17f03

…ines.md Co-authored-by: Lee White <[email protected]>

Update website/docs/components/code-editor/partials/guidelines/guidel…

c803396

…ines.md Co-authored-by: Lee White <[email protected]>

Update website/docs/components/code-editor/partials/guidelines/guidel…

6aa5247

…ines.md Co-authored-by: Lee White <[email protected]>

zamoore force-pushed the Lilith-Design-Documentation-CodeEditor-Linting branch from e8c2b5c to 6aa5247 Compare March 7, 2025 19:56

vercel bot deployed to Preview – hds-showcase March 7, 2025 19:57 View deployment

vercel bot deployed to Preview – hds-website March 7, 2025 20:00 View deployment

heatherlarsen reviewed Mar 7, 2025

View reviewed changes

zamoore merged commit 6aa5247 into zamoore/HDS-4361/CodeEditor-linting-website Mar 7, 2025
14 of 16 checks passed

zamoore deleted the Lilith-Design-Documentation-CodeEditor-Linting branch March 7, 2025 20:13

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Design documentation for CodeEditor linting #2752

Design documentation for CodeEditor linting #2752

LilithJames-HDS commented Mar 6, 2025

vercel bot commented Mar 6, 2025 •

edited

Loading

majedelass left a comment

andgen404 left a comment

andgen404 Mar 6, 2025

LilithJames-HDS Mar 6, 2025

zamoore Mar 6, 2025

jorytindall left a comment

heatherlarsen left a comment

heatherlarsen Mar 6, 2025

LilithJames-HDS Mar 7, 2025

heatherlarsen Mar 7, 2025

heatherlarsen Mar 6, 2025

shleewhite left a comment

heatherlarsen left a comment

heatherlarsen Mar 7, 2025

heatherlarsen Mar 7, 2025

	## Linting (JSON language only)
	### Linting (JSON language only)

	The Code Editor supports linting for JSON using [CodeMirror6](https://codemirror.net/examples/lint/). This feature highlights all errors with an underline and an icon next to the line number. Each icon has a tooltip explaining the error on the associated line. To view all alerts in the editor, users can open a dialog using Ctrl-Shift-m (Cmd-Shift-m on macOS).
	The Code Editor supports linting for JSON using [CodeMirror6](https://codemirror.net/examples/lint/). This feature highlights all errors with an underline and an icon next to the line number. Each icon has a tooltip explaining the error on the associated line.

Design documentation for CodeEditor linting #2752

Design documentation for CodeEditor linting #2752

Conversation

LilithJames-HDS commented Mar 6, 2025

📌 Summary

🛠️ Detailed description

🔗 External links

vercel bot commented Mar 6, 2025 • edited Loading

majedelass left a comment

Choose a reason for hiding this comment

andgen404 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jorytindall left a comment

Choose a reason for hiding this comment

heatherlarsen left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shleewhite left a comment

Choose a reason for hiding this comment

heatherlarsen left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vercel bot commented Mar 6, 2025 •

edited

Loading