Replies: 8 comments 4 replies
-
|
One thing to consider, would be whether we want to align to or deviate from GDS. (I think we should be fairly close at the moment. And what you've got above looks pretty close too.) |
Beta Was this translation helpful? Give feedback.
-
|
FWIW, In the GDS version I think "How to use this component" would be blended into "How it works". |
Beta Was this translation helpful? Give feedback.
-
|
Sometimes we might not actually need the accessibility heading. |
Beta Was this translation helpful? Give feedback.
-
|
Discussed at design system working group. Wondered if 'Contribute' was not as inviting as 'Help improve this component'. And consider any standard wording if we haven't got content yet for the research bit. |
Beta Was this translation helpful? Give feedback.
-
|
Suggested improvment Heading 1: Component name Heading 2: When to use this component Heading 2: How it works Heading 2: How to use this component Heading 2: Accessibility Heading 2: Research Heading 2: Help improve this component |
Beta Was this translation helpful? Give feedback.
-
|
Feedback about needing a 'Writing for this component' as a heading level 2, and moving the placement section under 'How it works'. |
Beta Was this translation helpful? Give feedback.
-
|
Heading 1: Component name Heading 2: When to use this component Heading 2: How it works Heading 2: Writing for this component Heading 2: Accessibility Heading 2: Research Heading 2: Help improve this component |
Beta Was this translation helpful? Give feedback.
-
|
The changes to standardise the component pages can be viewed here: https://62f3df93fa4c5d0d2b9cd63e--hods.netlify.app/components (See the pull request #444) |
Beta Was this translation helpful? Give feedback.
-
|
There could be an overlap between accessibility and research, particularly with the page example where the research referenced was mostly on accessibility. Might there be times where you can merge headers or drop one? |
Beta Was this translation helpful? Give feedback.
-
|
I'd agree with @Sarah-Lombardi that there should be some flex in what headers are included, to help with clarity for individual components. @tomyems will this guidance be stored somewhere internally (GitHub and/or Sharepoint), so that if we create new pages in future we can follow the guidelines? |
Beta Was this translation helpful? Give feedback.
-
|
My plan so far was to keep this discussion open, to use it as the record for what headers should be included. If that doesn't work, or you think it's better in another place, I'm all ears. |
Beta Was this translation helpful? Give feedback.
-
|
Latest version: https://6304ccddfb22d77dee029268--hods.netlify.app/components |
Beta Was this translation helpful? Give feedback.
-
The components pages have different and inconsistent heading structures. The proposal is to align them to have the same structure:
Heading 1: Component name
One line introduction, followed by example with Props.
Heading 2: When to use this component
More detailed description about how this component solves a problem.
Heading 2: How it works
Detailed examples showing different ways of using the component, including HTML and React code snippets.
Heading 2: How to use this component
Describe the best practice for the text used, and how it interacts with the rest of the page.
Heading 2: Accessibility
Guidance about how to use the component accessibly.
Heading 2: Research
Any research insights, including services currently using the component.
Heading 2: Contribute
Link to github discussion about the component, pointing out any known gaps.
Beta Was this translation helpful? Give feedback.
All reactions