From e8130b79592ea38cb93f177da06a5ed23f1b5e7a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marianne=20R=C3=B8svik?= Date: Wed, 23 Aug 2023 12:46:34 +0200 Subject: [PATCH] docs: improved alert guidelines (#745) Co-authored-by: Michael Marszalek --- .../Information/Information.module.css | 23 +- docs-components/Information/Information.tsx | 11 +- packages/react/src/components/Alert/Alert.mdx | 107 ++++++++- .../src/components/Alert/Alert.stories.tsx | 217 ++++++++++++------ 4 files changed, 261 insertions(+), 97 deletions(-) diff --git a/docs-components/Information/Information.module.css b/docs-components/Information/Information.module.css index 41082d4bea..b28428090a 100644 --- a/docs-components/Information/Information.module.css +++ b/docs-components/Information/Information.module.css @@ -1,10 +1,4 @@ .container { - background-color: var(--fds-semantic-surface-warning-subtle); - border-left: 8px solid var(--fds-semantic-border-warning-default); - padding: 1.5rem; - display: flex; - flex-direction: column; - width: auto; margin-top: 24px !important; margin-bottom: 2rem !important; } @@ -17,15 +11,32 @@ } .beta { + padding: 1.5rem; + display: flex; + flex-direction: column; + width: auto; background-color: #f1ecff; border-left: 8px solid #6544c5; } .danger { + padding: 1.5rem; + display: flex; + flex-direction: column; + width: auto; background-color: var(--fds-semantic-surface-danger-subtle); border-left: 8px solid var(--fds-semantic-border-danger-default); } +.warning { + padding: 1.5rem; + display: flex; + flex-direction: column; + width: auto; + background-color: var(--fds-semantic-surface-warning-subtle); + border-left: 8px solid var(--fds-semantic-border-warning-default); +} + .title { font: var(--fds-typography-heading-xxsmall) !important; border-bottom: 0 !important; diff --git a/docs-components/Information/Information.tsx b/docs-components/Information/Information.tsx index 68ef1ec68b..73e7eb3e54 100644 --- a/docs-components/Information/Information.tsx +++ b/docs-components/Information/Information.tsx @@ -1,5 +1,6 @@ import React from 'react'; import { Markdown } from '@storybook/blocks'; +import cn from 'classnames'; import classes from './Information.module.css'; @@ -7,9 +8,9 @@ type Texts = 'token' | 'development' | 'beta' | 'deprecated'; const texts: Record = { token: { - title: 'Tokens', + title: '', description: - 'Husk å importere ny tokens-pakke **`@digdir/design-system-tokens/brand//tokens.css`** før du tar i bruk denne komponenten.\n\n Importer tokens i henhold til ditt brand; `altinn`, `digdir` eller `tilsynet`.', + 'Husk å importere ny tokens-pakke **`@digdir/design-system-tokens/brand//tokens.css`** før du tar i bruk denne komponenten.\n\n Importer tokens i henhold til ditt brand; `altinn`, `digdir`, `brreg` eller `tilsynet`.', }, development: { title: 'Under utvikling', @@ -34,8 +35,10 @@ const colorClass = (text: Texts) => { return classes.beta; case 'deprecated': return classes.danger; + case 'development': + return classes.warning; default: - return ''; + return null; } }; @@ -48,7 +51,7 @@ export const Information = ({ text, description }: InformationProps) => { const textData = texts[text]; return ( -
+
{textData.title &&

{textData.title}

}
{`${textData.description} \n\n ${ diff --git a/packages/react/src/components/Alert/Alert.mdx b/packages/react/src/components/Alert/Alert.mdx index 20aa27a4e1..99948aa572 100644 --- a/packages/react/src/components/Alert/Alert.mdx +++ b/packages/react/src/components/Alert/Alert.mdx @@ -6,7 +6,12 @@ import * as AlertStories from './Alert.stories'; # Alert -`Alert` skal brukes til å vise viktige meldinger, varsler eller advarsler til brukere. Den er designet for å fange brukernes oppmerksomhet og gi dem relevant informasjon som krever handling eller gjøre dem bevisst på viktig informasjon +Bruk `Alert` til budskap det er ekstra viktig at brukerne ser og forstår. Den er designet for å fange brukernes oppmerksomhet. Vær sikker på at budskapet er så tydelig at det gir mening selv om teksten er svært kort. + +**Vær oppmerksom på:** + +- Bruk komponenten varsomt. Brukere kan forveksle varsler med reklame, og dermed overse dem. Hvis vi bruker varsler ofte, kan vi forverre dette problemet. +- Du skal _ikke_ bruke `Alert` som feilmelding til et enkelt skjemaelement. Alle komponenter har egen feilmelding til dette formålet. @@ -22,26 +27,104 @@ import { Alert } from '@digdir/design-system-react'; You are using the Alert component!; ``` -## Tilgjengelighet +## Varianter med eksempler + +`Alert` har flere varianter fordi den kan brukes til fire ulike budskap: Informasjon, advarsler, suksess og feilmelding. + +
+ +### Informasjon + +Bruk `info` til informasjon som er nyttig for brukerne, men ikke avgjørende for at de skal forstå oppgaven. + + + +### Suksess + +Bruk `success` når du vil bekrefte at brukeren har fullført en oppgave, at handlingen var vellykket. -### Alternativ-tekst + -Ikonene er ikke bare dekorative. De har default alternativ-tekst som kommuniserer alvorlighetsgrad: "Informasjon", "Suksess", "Advarsel" og "Feil". Denne blir lest opp som en del av innholdet for skjermleserbrukere. +### Advarsel -### Interaksjon Skjermleser +Bruk `warning` når du vil at brukeren skal foreta en bestemt handling eller for å advare dem om noe viktig. -Alert-komponenten er ikke en ARIA live region og er ikke relatert til ARIA `role="alert"`. Komponenten skal ikke motta dynamiske oppdateringer. Den blir presentert for skjermleserbrukere som vanlig statisk innhold. + -Du kan legge på `role=alert` men vær opperksom på forventet oppførsel dette medfører. Les mer om dette på [W3 Alert pattern](https://www.w3.org/WAI/ARIA/apg/patterns/alert/) +### Feilmelding -## Eksempler +Bruk `danger` for å informere om noe som er kritisk eller som hindrer brukeren i å komme videre. -### Med Heading + -Dersom du ønsker en tittel i komponenten så kan du bruke [Typografi](/docs/kjernekomponenter-typography--docs) komponentene. Husk å velg riktig `Heading` nivå basert `Alert` sin plass i innholdstruktur på siden. +## Andre eksempler + +`Alert` kan brukes sammen med andre komponenter og stiler. Her er noen eksempler. + +
+ +### Med overskrift + +Hvis meldingen er lenger enn en setning kan det være nyttig å bruke en overskrift til å fremheve det viktigste. Dette kan gjøres ved bruk av [Typografi](/docs/kjernekomponenter-typography--docs)-komponentene. Husk å velg riktig overskriftsnivå ut fra plassen alert har i innholdsstrukturen på siden. -### Andre eksempler +Dersom tittel og beskrivelse gjentar det samme er det bedre å bruke en enkel setning uten overskrift. + + + +### Med lenke + +Du kan ha en lenke i Alert hvis det hjelper brukeren å løse oppgaven. Men vær obs på at en lenke tar brukeren ut av tjenesten, så bruk lenke kun når det er absolutt nødvendig, for eksempel hvis du vil at brukeren skal åpne et skjema eller utføre en viktig oppgave. + + + +### Med skygge + +Kan brukes når alerten skal fremheves mer fra bakgrunnen, for eksempel dersom den skal legges over annet innhold + + + +## Tekst i komponenten + +Det er ikke alle som intuitivt forstår forskjellen på varslene selv om de har ulike ikoner og farger. Derfor er det viktig at ordene du bruker gjør det klart for brukerne hvordan de skal forholde seg til informasjonen i varselet. + +Det må være tydelig hvem som gjør hva. Tenk på teksten som en samtale med brukeren, bruk ord som «vi» og «du». + +Hvis meldingen er knyttet til en bestemt handling, for eksempel svar på et spørsmål, bør teksten gjenta nøkkelord fra label. + +Det er spesielt viktig at teksten i feilmeldingene forteller om det er noe brukene må eller kan gjøre for å komme videre med oppgaven sin. Her er en liste med hvilken type informasjon en feilmelding bør inneholde: + +- Fortell hva som har skjedd + - Eksempel: "Kunne ikke koble til konto." +- Fortell hvorfor det skjedde + - Eksempel: "Vi kunne ikke koble til kontoen din på grunn av tekniske problemer fra vår side." +- Forsikre brukeren + - Eksempel: "Endringene dine har blitt lagret." +- Gi dem en vei ut av problemet + - Eksempel: "Hvis dette problemet oppstår igjen, kontakt Kundeservice." +- Hjelp dem å fikse problemet selv + - Eksempel: "Vennligst prøv igjen." +
+ +## Tilgjengelighet + +### Alternativtekst + +Ikonene er ikke bare dekorative. De har en standard alternativtekst som kommuniserer alvorlighetsgrad: "Informasjon", "Suksess", "Advarsel" og "Feil". Denne blir lest opp som en del av innholdet for skjermleserbrukere. + +### Interaksjon med skjermleser + +Alert-komponenten kommer ikke med en `role="alert"` som default, den blir presentert for skjermleserbrukere som vanlig statisk innhold. Du kan legge på `role=alert` selv, men vær opperksom på forventet oppførsel dette medfører. Du kan lese mer om dette på [dokumentasjonen til ARIA](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role). + +#### Ikke gjør dette + +Ikke bruk `role=alert` om alert er synlig når siden lastes inn. + + + +#### Gjør dette + +Bruk `role=alert` hvis den dukker opp dynamisk underveis pga brukerinput eller andre faktorer som kan trigge en alert. - + diff --git a/packages/react/src/components/Alert/Alert.stories.tsx b/packages/react/src/components/Alert/Alert.stories.tsx index fa84c592d8..606679b9c9 100644 --- a/packages/react/src/components/Alert/Alert.stories.tsx +++ b/packages/react/src/components/Alert/Alert.stories.tsx @@ -1,8 +1,7 @@ import React from 'react'; import type { Meta, StoryFn } from '@storybook/react'; -import { Stack } from '../../../../../docs-components'; -import { Heading, Paragraph } from '../'; +import { Heading, Paragraph, Link } from '../'; import { Alert } from '.'; @@ -16,87 +15,155 @@ export default { }, } as Meta; -export const Preview: Story = (args) => ( - Nå kan du sende inn søknaden -); +export const Preview: Story = (args) => ; Preview.args = { severity: 'info', elevated: false, + children: 'En beskjed det er viktig at brukeren ser', }; +export const VariantInfo: Story = () => ( + + + Har du husket å bestille passtime? + + + Det er lange køer for å bestille pass om dagen, det kan være lurt å + bestille i god tid før du skal reise. + + +); + +export const VariantSuccess: Story = () => ( + + + Gratulerer! Du kan nå starte selskapet ditt + + + Det ser ut til at regnestykket går i pluss og at du har det som skal til + for å starte selskapet ditt. + + +); + +export const VariantWarning: Story = () => ( + + + Vi har tekniske problemer + + + Det gjør at du kan bli avbrutt mens du fyller ut skjemaet. Vi jobber med å + rette problemene. + + +); + +export const VariantDanger: Story = () => ( + + + Det har skjedd en feil + + + Vi klarer ikke å hente informasjonen du ser etter akkurat nå. Prøv igjen + litt senere. Hvis vi fortsatt ikke klarer å vise informasjonen du trenger, + tar du kontakt med kundeservice på telefon 85 44 32 66. + + +); + export const MedHeading: Story = () => ( - <> - - - Har du husket å bestille passtime? - - - Det er lange køer for å bestille pass om dagen, det kan være lurt å - bestille i god tid om du trenger pass til sommeren. - - - + + + Har du husket å bestille passtime? + + + Det er lange køer for å bestille pass om dagen, det kan være lurt å + bestille i god tid om du trenger pass til sommeren. + + +); + +export const MedKunHeading: Story = () => ( + + Du har 7 dager igjen på å fullføre søknaden. + +); + +export const MedLenke: Story = () => ( + + + Søknadsfristen går ut om 3 dager + + + Fristen for å søke opptak til utdanning er 15. april.{' '} + Søk nå + + +); + +export const MedShadow: Story = () => ( + + Skjema er lagret automatisk. + ); -export const Eksempler: Story = () => ( - <> - - Skjemaet er lagret automatisk - - - - Det ser ut til at regnestykket ditt går i pluss og at du har det som - skal til for å lykkes i oppstartsfasen av ditt selskap. - - - - - Du blir snart logget ut - - - Du har nå vært inaktiv i 15 minutter og vil bli automatisk logget ut om - du ikke foretar deg noe på innen 5 minutter. - - - - - Du blir snart logget ut - - - - - - Beklager, men det har skjedd en feil - - - Vi klarer ikke å hente informasjonen du ser etter akkurat nå. Prøv igjen - litt senere. Om vi fortsatt ikke klarer å vise informasjonen, ta kontakt - med kundeservice. - - - +export const UtenAria: Story = () => ( + + + Nedetid + + + I natt klokken 00:00 til 02:00 vil nettsiden være nede på grunn av + vedlikehold. + + ); -Eksempler.decorators = [ - (Story) => ( - - - - ), -]; +export const MedAria: Story = () => ( + + + Vi klarer ikke lagre skjema + + + Vi har mistet forbindelsen med serveren og får ikke lagret skjema. Vent + litt og prøv en gang til. + + +);