Merge pull request #162 from City-of-Helsinki/fix/more-documentation-…

…fixes

[Fix] Documentation fixes and improvements

site/docs/about/new.mdx

@@ -5,20 +5,21 @@ menu: About
 ---
 
 import LargeParagraph from "../../src/components/LargeParagraph";
-
+import Link from "../../src/components/Link";
 
 # What is new
 
 <LargeParagraph>
-    Here you will find summarized patch notes of major releases of HDS. For full patch notes for each release, please refer to the <a href="https://github.com/City-of-Helsinki/helsinki-design-system/releases">GitHub releases</a>.
+    Here you will find summarized patch notes of major releases of HDS. For full patch notes for each release, please refer to the <Link href="https://github.com/City-of-Helsinki/helsinki-design-system/releases" external>GitHub releases</Link>.
 </LargeParagraph>
 
-**0.11.0 (alpha)** - [Release notes](https://github.com/City-of-Helsinki/helsinki-design-system/releases/tag/v0.11.0)
+<p><b>0.11.0 (alpha)</b> - <i>02/06/2020</i> - <Link href="https://github.com/City-of-Helsinki/helsinki-design-system/releases/tag/v0.11.0" external>Release notes</Link></p>
+
 - **Added**: New icons
 - **Added**: New design tokens for breakpoints and maximum content widths
 - **Changed**: Updated HDS icon library and documentation
 
-**0.10.0 (alpha)** - [Release notes](https://github.com/City-of-Helsinki/helsinki-design-system/releases/tag/v0.10.0)
+<p><b>0.10.0 (alpha)</b> - <i>26/05/2020</i> - <Link href="https://github.com/City-of-Helsinki/helsinki-design-system/releases/tag/v0.10.0" external>Release notes</Link></p>
 
 - **Added**: New components Button, Checkbox, Dropdown, Koros, Radio button, Text input and Text area
 - **Added**: New design tokens for Colour, Typography and Spacing

site/docs/about/roadmap.mdx

@@ -29,12 +29,12 @@ import LargeParagraph from "../../src/components/LargeParagraph";
 
 **Q3 2020**
 
-> Coming soon!
+_Coming soon!_
 
 **Q4 2020**
 
-> Coming soon!
+_Coming soon!_
 
 **2021**
 
-> Coming soon!
+_Coming soon!_

site/docs/about/statement.mdx

@@ -4,6 +4,8 @@ route: /about/accessibility-statement
 menu: About
 ---
 
+import Link from "../../src/components/Link";
+
 # Accessibility statement
 
 This accessibility statement applies to the website Helsinki Design System (documentation). The site address is hds.hel.fi.
@@ -24,7 +26,7 @@ This statement was prepared on 22/05/2020.
 The accessibility statement will be updated so that it corresponds with the observations related to accessibility compliance made during an audit.
 
 ### Requesting information in an accessible format
-If a user feels that content on a website is not available in an accessible format, they can request for this information by e-mail at [email protected] or through the [feedback form](https://www.hel.fi/helsinki/en/administration/participate/feedback). The aim is to reply to the enquiry within a reasonable time frame.
+<p>If a user feels that content on a website is not available in an accessible format, they can request for this information by e-mail at [email protected] or through the <Link href="https://www.hel.fi/helsinki/en/administration/participate/feedback" external>feedback form</Link>. The aim is to reply to the enquiry within a reasonable time frame.</p>
 
 ### Feedback and contact information
 City of Helsinki, City Executive Office, Helsinki Design System team ([email protected])

site/docs/about/support.mdx

@@ -5,6 +5,7 @@ menu: About
 ---
 
 import LargeParagraph from "../../src/components/LargeParagraph";
+import Link from "../../src/components/Link";
 
 # Support
 
@@ -21,16 +22,16 @@ If you’ve got a question or a suggestion, you can get in touch with the team b
 
 ### Slack channels
 HDS team members can also be reached in two Slack channels in the City of Helsinki Slack.
-- [#designsystem](https://helsinkicity.slack.com/archives/CHCV3KTHA) for design related discussion
-- [#designsystem-dev](https://helsinkicity.slack.com/archives/CMW0FGFM5) for implementation related discussion
+- <Link href="https://helsinkicity.slack.com/archives/CHCV3KTHA" external>#designsystem</Link> for design related discussion
+- <Link href="https://helsinkicity.slack.com/archives/CMW0FGFM5" external>#designsystem-dev</Link> for implementation related discussion
 
 ## Issues and features
 
 ### Submitting an issue
-You can submit issues and bug reports to [HDS repository in GitHub](https://github.com/City-of-Helsinki/helsinki-design-system).
+<p>You can submit issues and bug reports to <Link href="https://github.com/City-of-Helsinki/helsinki-design-system" external>HDS repository in GitHub</Link>.</p>
 
 ### Feature requests
-You can submit feature requests to [HDS repository in GitHub](https://github.com/City-of-Helsinki/helsinki-design-system) as issues labeled "feature-request". You can also get in touch with HDS team with any of the above-mentioned methods.
+<p>You can submit feature requests to <Link href="https://github.com/City-of-Helsinki/helsinki-design-system" external>HDS repository in GitHub</Link> as issues labeled "feature-request". You can also get in touch with HDS team with any of the above-mentioned methods.</p>
 
 ### Contributing
 See [Contributing](/contributing).

site/docs/components/buttons.mdx

@@ -9,6 +9,7 @@ import { Button, IconShare, IconAngleRight } from "hds-react";
 
 import ColorBox from "../../src/components/ColorBox";
 import LargeParagraph from "../../src/components/LargeParagraph";
+import Link from "../../src/components/Link";
 import Text from "../../src/components/Text";
 
 # Buttons
@@ -92,7 +93,7 @@ Supplementary buttons can be used in similar cases as secondary buttons. However
 ```
 
 ### Icon buttons
-Icons can be added to buttons to make the action easier to understand. Sometimes it can be also beneficial to add icons to make important actions more distinguishable. It is not recommended to use buttons with icons without text label because users interpret icons in different ways. More information on icon usage in the [icon guideleines](/visual-assets/icons "Icons").
+Icons can be added to buttons to make the action easier to understand. Sometimes it can be also beneficial to add icons to make important actions more distinguishable. It is not recommended to use buttons with icons without text label because users interpret icons in different ways. More information on icon usage in the [icon guidelines](/visual-assets/icons "Icons").
 
 <Playground>
   <Button iconLeft={<IconShare />}>Button</Button>
@@ -156,11 +157,11 @@ It is recommended to use the standard button size in most cases. If there is a b
 ```
 
 ### Utility buttons
-If required to achieve clearer user interface, you may also use additional utility colors. Different visual styles of these buttons can be used to better inform users of destructive or dangerous actions. To comply with WCAG requirement 1.4.1 Use of Color, these colors are more accessible when paired with an icon.
+<p>If required, to achieve clearer user interface, you may also use additional utility colors. Different visual styles of these buttons can be used to better inform users of destructive or dangerous actions. To comply with <Link href="https://www.w3.org/TR/WCAG21/#use-of-color" external>WCAG requirement 1.4.1 Use of Color</Link>, these colors are more accessible when paired with an icon.</p>
 
 <Playground>
-  <Button variant="success">Success</Button>
-  <Button variant="danger" style={{marginLeft: 'var(--spacing-s)'}}>Danger</Button>
+  <Button variant="success">Save</Button>
+  <Button variant="danger" style={{marginLeft: 'var(--spacing-s)'}}>Delete</Button>
 </Playground>
 
 ##### Core:

site/docs/components/component_overview.mdx

@@ -5,6 +5,7 @@ route: /components
 ---
 
 import LargeParagraph from "../../src/components/LargeParagraph";
+import Link from "../../src/components/Link";
 
 # Component overview
 
@@ -20,15 +21,15 @@ The core package provides Helsinki City brand colours, typography and base style
 
 The core components and technical documentation are available in [Helsinki Design System Core Storybook](/storybook/core).
 
-[View hds-core in GitHub](https://github.com/City-of-Helsinki/helsinki-design-system/tree/master/packages/core)
+<Link href="https://github.com/City-of-Helsinki/helsinki-design-system/tree/master/packages/core" external>View hds-core in GitHub</Link>
 
 ### React components
 
 Helsinki Design System React library provides a collection of React component for building websites and applications. Using the components will help developers to rapidly create user interfaces that are in line with the Helsinki City Design Language as well as accessible and consistent in behavior across applications.
 
 The React components and technical documentation are available in [Helsinki Design System React Storybook](/storybook/react).
 
-[View hds-react in GitHub](https://github.com/City-of-Helsinki/helsinki-design-system/tree/master/packages/react)
+<Link href="https://github.com/City-of-Helsinki/helsinki-design-system/tree/master/packages/react" external>View hds-react in GitHub</Link>
 
 ## Component status
 
@@ -42,7 +43,7 @@ Component                                                        | Status
 [Checkbox](/components/checkbox)                                 | Stable       | [✔](/storybook/core/?path=/story/checkbox--default)     | [✔](/storybook/react/?path=/story/components-checkbox--default)
 [Dropdown](/components/dropdown)                                 | Stable       |                                                         | [✔](/storybook/react/?path=/story/components-dropdown--default)
 [Icons](/visual-assets/icons)                                    | Stable       | [✔](/storybook/core/?path=/story/icons--angle-down)     | [✔](/storybook/react/?path=/story/components-icons--iconangledown)
-[Koros](/components/koros)                                       | Stable       |                                                         | [✔](/storybook/react/?path=/story/components-koros--basic)
+[Koros (wave elements)](/components/koros)                                       | Stable       |                                                         | [✔](/storybook/react/?path=/story/components-koros--basic)
 [Radio button](/components/radio-button)                         | Stable       | [✔](/storybook/core/?path=/story/radiobutton--default)  | [✔](/storybook/react/?path=/story/components-radiobutton--default)
 [Text input](/components/text-field)                             | Stable       | [✔](/storybook/core/?path=/story/textinput--default)    | [✔](/storybook/react/?path=/story/components-textinput--default)
 [Text area](/components/text-field#text-area)                    | Stable       | [✔](/storybook/core/?path=/story/textarea--default)     | [✔](/storybook/react/?path=/story/components-textarea--default)

site/docs/components/dropdown.mdx

@@ -14,12 +14,12 @@ import LargeParagraph from "../../src/components/LargeParagraph";
 # Dropdowns
 
 <LargeParagraph>
-  Dropdown offers user a list of options which one or multiple can be selected. Dropsdowns are often used as part of forms and filters.
+  A dropdown offers user a list of options which one or multiple can be selected. Dropdowns are often used as part of forms and filters.
 </LargeParagraph>
 
 ## Principles
 
-- **Label should be always provided with dropdowns.** Aim for labels that are short, concise and easy to understand.
+- **A label should always be provided with dropdowns.** Aim for labels that are short, concise and easy to understand.
 - Dropdowns usually have four (4) or more options. When having only 2-4 options, it is usually better to use [radio button group](/components/radio-button). Also, if options need to be easily comparable (for example, product pricing), prefer radio buttons over dropdown.
 - It is recommended to set default option for the dropdown. If the default option is also the recommended option, you can mark the option with text "_(recommended)_".
 - If your dropdown has 8 or more options, consider using the [filterable](/components/dropdown#filterable) variant so the user can locate the wanted option easier.

site/docs/components/icons.mdx

@@ -8,6 +8,7 @@ import { Playground } from "docz";
 import { IconFaceSmile } from "hds-react";
 
 import LargeParagraph from "../../src/components/LargeParagraph";
+import Link from "../../src/components/Link";
 
 # Icon
 
@@ -23,9 +24,9 @@ See the [icon library documentation](/visual-assets/icons "HDS Icons") for more
 - **An icon and its related content or label should have the same meaning.** Conflicting and ambivalent interpretations can have a negative effect on usability and accessibility.
 
 ## Accessibility
-- A text alternative must always be provided for icons using the WAI-ARIA definition _aria-label_ or _aria-labelledby_. See [WCAG Text Alternatives guideline](https://www.w3.org/TR/WCAG21/#text-alternatives "WCAG 2.1 Text Alternatives") for more information.
+- A text alternative must always be provided for icons using the WAI-ARIA definition _aria-label_ or _aria-labelledby_. See <Link href="https://www.w3.org/TR/WCAG21/#text-alternatives" external>WCAG 2.1 Text Alternatives guideline</Link> for more information.
 - Illustrative icons should use the WAI-ARIA definition _role='presentation'_.
-- The colour contrast between the icon and its background must comply with [AA Level contrast ratios](https://www.w3.org/TR/WCAG21/#distinguishable "WCAG 2.1 Distinguishable").
+- The colour contrast between the icon and its background must comply with <Link href="https://www.w3.org/TR/WCAG21/#contrast-minimum" external>AA Level contrast ratios</Link>.
 
 
 ## Usage

site/docs/components/koros.mdx

@@ -8,6 +8,7 @@ import { Playground } from "docz";
 import { Koros } from "hds-react";
 
 import LargeParagraph from "../../src/components/LargeParagraph";
+import Link from "../../src/components/Link";
 
 # Koros
 
@@ -21,14 +22,15 @@ import LargeParagraph from "../../src/components/LargeParagraph";
 - Koros is a very powerful visual element. Use them sparingly in one view.
 - Koros should be only used as filled. Do not use empty fill koros with borders.
 - Use koros as part of a background. Do not create new visual elements using koros.
+- It is allowed to animate Koros shapes (not included in the HDS yet).
 
 ## Accessibility
 
 - It is allowed to use Koros in all brand colors. When choosing colours, refer to [colour guidelines](/design-tokens/colour "Colour") to ensure accessibility.
 
 ## Usage
 
-There are five Koro styles. An added visual interest is brought to the identity by means of the Koros. Using Koros adds high visual impact and makes the user interface recognisable as part of Helsinki city services. You can read more about using Koros in [Helsinki Visual Identity Guidelines](https://brand.hel.fi/en/wave-motifs/).
+<p>There are five Koro styles. An added visual interest is brought to the identity by means of the Koros. Using Koros adds high visual impact and makes the user interface recognisable as part of Helsinki city services. You can read more about using Koros in <Link href="https://brand.hel.fi/en/wave-motifs/" external>Helsinki Visual Identity Guidelines - Wave motifs</Link>.</p>
 
 <Playground>
   <Koros type="basic" />

site/docs/components/radio_button.mdx

@@ -21,7 +21,7 @@ import Text from "../../src/components/Text";
 
 - If the user can select more than one option from a list, use [checkboxes](/components/checkbox) instead.
 - Radio button label should always describe clearly what will happen if the specific option is chosen. A good practice is to keep labels at maximum of three words long.
-- Radio button groups should have a default option selected.
+- It is recommended to have default option checked for radio button groups Radio button groups.
 - When there are more than 4 options, consider switching to [dropdown](/components/dropdown) component.
 - If possible, align radio button groups vertically rather than horizontally. Vertical radio button groups are easier to read.
 

site/docs/components/text_fields.mdx

@@ -18,7 +18,7 @@ import Text from "../../src/components/Text";
 </LargeParagraph>
 
 ## Principles
-- **Label should be always provided with text fields.** Only exception to this is the search field which can be identified from the magnifying glass icon.
+- **A label should always be provided with a text field.** Only exception to this is the search field which can be identified from the magnifying glass icon.
 - Use a text input when a single line of text is expected. For multiline inputs, use a text area.
 - Allow the text input to reflect the length of the content you expect the user to enter.
 - If possible, add programmatic assistance. Detect and pre-fill inputs to reduce errors and save time. Use sentence-case for default values, detected values, and auto-completion text.