Create a default page structure for components

[PtitBen]

Outcome

We have a template to work with when we start creating each component's documentation page

Scope

This is the structure we agreed during our workshop:

Component name

Overview

• Name*
• Purpose (General + types)**
• Quick example***
• Related links

Guidance

• Types
  • Content Guidance
  • Examples (snippet + preview)***

Implementation

• Specs*
  • Specs notes
• Dos & Don'ts
• Best Practices
• Accessibility

Placement ***

Side widgets

• Related links (link to the overview's link section of the current component)
• Contribute/Edit this page
• Feedback

Automated to pull from custom-elements.json *
Automated to pull from custom-elements.json and manual content **
Reusable wrapper / component ***

[RobTobias123]

I've attempted a trial run at entering ns-accordion content in the format as outlined in the scope above. This helps assess if there's any issues. Content was copied from existing docs, some screenshots as placeholders for snippets etc, and I've add a few comments/questions in situ. I also added a custom.css on my branch and tweaked the main heading style slightly larger, because I wanted to see how that works in anticipation that we may need to fine tune things a touch once we can see how it is working. Eg. if we decided we needed a specific class that makes the main purpose 1 liner larger and bolder to make it more noticeable, or if we wanted to add the tag equivalent of the name as the first item below the main title and using code markdown but larger than normal etc.. My explorations can all be seen on on branch 'content-update' which I've commited and pushed.

[RobTobias123]

I've added content for all sections on the ns-accordion as a trial-fit. Let's discuss to see what might need changing. I am hoping to gain some insights from some user interviews I'll be setting up and then empathy mapping. This will help us understand what is important to the users and give us insights on heirarchy and usefulness of content, and understand the painpoints of the current way of working.

[RobTobias123]

Thoughts...

• Wondering if snippets for all variants should be on the initial page (if that's what people are coming here for most? Will find out)
• All pages title showing as 'Accordion' instead of Accordion guidance etc so it feels more part of the same parent.
• Do we want to use ns- prefix in front of all the items in the left hand menu? Would be easier to scan if Alphabetical starting with a capital? We can still display the 'tag' version of the name on the overview page immediately after the title (like Shoelace DS).
• Example needs to be a markdown heading in order to show in the RHS menu.
• Can we separate the automated 'purpose' from the example pulled in and use as the first line under 'Purpose' as shown? Feeling it needs to be there prominently before the example.

[MekalaNagarajan-Centrica]

Discovery work on code block, images #257

[RobTobias123]

Discovery work on general styles for Nucleus docs:

• There are light and dark modes to take advantage of in Astro.
• Created a list of colours from the Nucleus Logo combined with generalist colours for both modes.
• Set a typography style guide for h1 - h6 , paragraph, menu items including selected states. (Uses colours from those just defined). Roboto font selected as it is web-font, large x-height for legibility, narrower than the default characters for more perceieved horizontal space, multiple weights (using medium and regular).
• Colours checked for a11y contrast compliance.

There are still some to yet be considered such as links and captions. These below give an overall look and feel that helps it look more considered than default and Nucleus branded rather than BG. Let me know if you think we should reconsider any of these choices?

https://www.figma.com/file/WHYHlisicKpmJinGpVWNgh/245---Docs-styles?type=design&node-id=0%3A1&mode=design&t=GhEFNySKjP82g4q9-1

[RobTobias123]

The above styling I believe can be applied by creating a 'custom.css' file in the location shown, although I've only tried a couple of things using that for proof of concept. (We can also change the centre doc area displayed width as we require too).

[MekalaNagarajan-Centrica]

Build preview https://astro-discovery.nucleus-docs.pages.dev/

Sample pages with reusable astro components,

https://astro-discovery.nucleus-docs.pages.dev/components/ns-accordion/
https://astro-discovery.nucleus-docs.pages.dev/components/ns-accordion/guidance/
https://astro-discovery.nucleus-docs.pages.dev/patterns/

[RobTobias123]

I was looking at my Grammarly app (a useful tool to assist when writing things) and the following set could be correct for our tone of voice for the docs - let me know if you think this needs anything different. (I had considered using 'expert' but then thought the users would not be, so better to talk in their language.)

[andij]

Grammarly, Hemmingway and VSCode Copilot

Observing the response from both https://app.grammarly.com/ (using the settings above) and for https://hemingwayapp.com/

Using Copilot in VSCode:

---

Prompt to Copilot: review my document

Copilot response:

As an AI programming assistant, I can provide feedback on the structure and formatting of your document. Here's my review:

1. Introduction: Clear and concise. It explains what an accordion is and its use cases.

2. Content guidance: The table provides clear guidelines on the key components of an accordion. The image reference might need to be checked to ensure it's displaying correctly.

3. Best practice: The Do's and Don'ts table is a good way to quickly communicate best practices.

4. Considerations of best practices: This section provides additional guidance on how to use the accordion component effectively.

5. Usage: It's unclear what does without context. If this is a code snippet, it might be helpful to explain what it does.

6. Component placement: Similar to the Usage section, it's unclear what does without context.

7. Specification: The table clearly outlines the slots and their types.

8. Specification notes: This section provides additional details about the slots.

9. Feedback: The links to Github bugs and issues are a good way to encourage user feedback.

Overall, the document is well-structured and provides clear guidance on how to use the accordion component. It might be helpful to provide more context or explanations for the code snippets in the Usage and Component placement sections.

---

Prompt to Copilot: suggest grammatical changes

Copilot response:

Here are some suggested grammatical changes:

1. In the "Introduction" section, change "Accordion enables users to expand and collapse multiple sections of content." to "The accordion enables users to expand and collapse multiple sections of content."

2. In the "Content guidance" section, change "All expanders need to be related to the accordion's heading." to "All expanders should be related to the accordion's heading."

3. In the "Best practice" section, change "Make sure the heading relates to content" to "Ensure the heading relates to the content."

4. In the "Considerations of best practices" section, change "If there isn't a inherent logical order to the expanders, use alphabetical order for ease of scanning." to "If there isn't an inherent logical order to the expanders, consider using alphabetical order for ease of scanning."

5. In the "Specification notes" section, change "Heading level should be h2 or h3 depending on its place in the semantics of the page." to "The heading level should be h2 or h3, depending on its place in the semantics of the page."

---

Prompt to Copilot: apply these changes

Copilot response:

Here's your document with the suggested grammatical changes applied:

Before:

## Introduction

> Accordion enables users to expand and collapse multiple sections of content.

We use accordions to break down content into meaningful sections, helping to reduce information overload. Accordions are useful for things like frequently asked questions or displaying multiple blocks of related content inside an [ns-expander](components/ns-expander.md).

## Content guidance

![Accordion](images/ns-accordion/contentguidance-ns-accordion.webp)

| Key | Field type | Guidelines |
| :--- | :--- | :--- |
| A | Heading | The recommended length is between 4 and 12 words, not exceeding 50 characters in total.  |
| B | Content | Use between 1 and 8 [ns-expander](components/ns-expander.md) components. All expanders need to be related to the accordion's heading.|

## Best practice

| 💚 Do's | 💔 Don'ts |
| :---  | :---  |
| Use for FAQs | Use a background with an accordion as the expanded state is white |
| Use to split up related content | Use more than 8 expanders |
| Make sure the heading relates to content | Use for critical or to hide information (such as caveats) |
| Use as a supporting component to the rest of the page's content | Use as a solution to excessive copy on a page |
|  | Use as the only component on a page |

### Considerations of best practises

If you need more than 8 [ns-expander](components/ns-expander.md) components, you can use more than one accordion on the page.

If there isn't a inherent logical order to the expanders, use alphabetical order for ease of scanning.

After:

## Introduction

> The accordion enables users to expand and collapse multiple sections of content.

We use accordions to break down content into meaningful sections, helping to reduce information overload. Accordions are useful for things like frequently asked questions or displaying multiple blocks of related content inside an [ns-expander](components/ns-expander.md).

## Content guidance

![Accordion](images/ns-accordion/contentguidance-ns-accordion.webp)

| Key | Field type | Guidelines |
| :--- | :--- | :--- |
| A | Heading | The recommended length is between 4 and 12 words, not exceeding 50 characters in total.  |
| B | Content | Use between 1 and 8 [ns-expander](components/ns-expander.md) components. All expanders should be related to the accordion's heading.|

## Best practice

| 💚 Do's | 💔 Don'ts |
| :---  | :---  |
| Use for FAQs | Use a background with an accordion as the expanded state is white |
| Use to split up related content | Use more than 8 expanders |
| Ensure the heading relates to the content | Use for critical or to hide information (such as caveats) |
| Use as a supporting component to the rest of the page's content | Use as a solution to excessive copy on a page |
|  | Use as the only component on a page |

### Considerations of best practices

If you need more than 8 [ns-expander](components/ns-expander.md) components, you can use more than one accordion on the page.

If there isn't an inherent logical order to the expanders, consider using alphabetical order for ease of scanning.

GitHub Copilot suggested this question:

What are some common use cases for accordions in web development?

Copilot response:

Accordions are commonly used in web development for the following purposes:

1. FAQs: Accordions are perfect for Frequently Asked Questions pages, as they allow users to quickly navigate through questions and reveal the answers to the ones they're interested in.

2. Forms: In complex forms, accordions can be used to break down the form into manageable sections, making it less overwhelming for the user.

3. Product Descriptions: On e-commerce websites, accordions can be used to neatly present product details, specifications, reviews, and other related information.

4. Navigation Menus: In mobile or responsive designs, accordions can be used to collapse navigation menus, making the interface cleaner.

5. Content Heavy Pages: For pages with a lot of content, accordions can be used to break the content into sections, allowing users to expand only the sections they're interested in, making the page less cluttered.

Remember, while accordions can be very useful, they should be used sparingly and not for critical information that all users should see, as some users may not realize they need to expand the accordion to view the content.

Summary

Using Copilot to assist in the structure, grammar and content of our documents could be a time-saver, help with spelling and grammar and give us some insight to produce additional content.

Both Grammarly and Hemmingway have the option of using AI, but I've not tried either of these as they are part of their paid plans and I'm thinking that using these cloud apps may be an issue with Centrica security etc., even though our content will be public.

[RobTobias123]

Merged approved branch for fonts #259

[andij]

I've created a few component pages which differ from each other so we can evaluate the page structure for the different needs.

These components are:

• ns-accordion - standard
• ns-alert - simple but diverse
• ns-card - staple
• ns-inputter - complex
• ns-landmark - image heavy
• ns-tab - simple
• ns-timeline - diverse

[RobTobias123]

Looking at the results we had from the user research, it suggests that we might move 'Best Practice' and 'Dos & Don'ts' to the 'Guidance' section and Snippets to the 'Implementation' section as that's where they would be expected. Also, visual examples are highly appreciated by the users so comprehensive image examples of configured variants etc could be included in Guidance too.

[RobTobias123]

Added a comment re testing the structure on the User research ticket... #256 (comment)

[MekalaNagarajan-Centrica]

Code snippet component #268

[andij]

Following our user research we discovered that there was a need for prominent navigation between the sections of each component, this reaffirmed our hypothesis that splitting the component page into Overview, Guidance, Implementation (as detailed in the scope of this ticket) is very useful.

Unfortunately the inclusion of these sections in the LHS navigation caused finability issues.

Our preferred solution to this was to revert back to the original design Jon had by including section tabs across the top of the page and making them sticky, so they are persistent.

During our discovery into the page structure we uncovered an unwanted side effect of splitting each component page into individual files. The affected areas were Search, Pagination and Mobile navigation.

We have reorganised the content to have one file for each component.

To add the section tabs we can use the TableOfContents (which is used in the RHS navigation) but show only the H2's.

The structure of the markdown now informs the section tabs. Here are a few examples of how the component pages headings are structured:

Accordion	Alert	Card	Landmark	Inputter

[andij]

At this point in time, we are happy with the initial default page structure for the component pages.

Ticket to track the implementation:

• Add HTML examples to relative directories in Docs #315

The PR to build the initial component page structure is:

• Feature/page content setup #317