Merge branch 'tooltip' of https://github.com/swisspost/design-system …

…into tooltip

.changeset/bright-dragons-exist.md

@@ -0,0 +1,6 @@
+---
+'@swisspost/design-system-documentation': patch
+'@swisspost/design-system-styles': patch
+---
+
+Internalized bootstrap border utility classes.

.changeset/nervous-glasses-pay.md

@@ -0,0 +1,5 @@
+---
+'@swisspost/design-system-styles': patch
+---
+
+Updated header button styles to match the header anchor styles.

.changeset/quick-vans-rule.md

@@ -0,0 +1,5 @@
+---
+'@swisspost/design-system-documentation': patch
+---
+
+Added documentation for developing and designing accessible webpages.

.changeset/three-elephants-sleep.md

@@ -0,0 +1,5 @@
+---
+'@swisspost/design-system-styles': patch
+---
+
+Cleaned up \_button.scss by moving button-specific variables to button.scss. Redefined cross-referenced variables in respective component files. Removed unused variables.

packages/documentation/.storybook/blocks/layout/layout.scss

@@ -30,7 +30,7 @@
 
 .docs-footer {
   > div:first-child {
-    background-color: post.$light;
+    background-color: post.$white;
   }
 
   ul.list-profile {

packages/documentation/.storybook/styles/preview.scss

@@ -220,3 +220,27 @@ $monospace: SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier
     right: 0;
   }
 }
+
+.light-section {
+  position: relative;
+  background-color: post.$white;
+
+  &:before,
+  &:after {
+    display: block;
+    content: '';
+    position: absolute;
+    top: 0;
+    bottom: 0;
+    background-color: inherit;
+    width: 100vw;
+  }
+
+  &:before {
+    right: 100%;
+  }
+
+  &:after {
+    left: 100%;
+  }
+}

packages/documentation/cypress/snapshots/utilities/borders.snapshot.ts

@@ -0,0 +1,13 @@
+describe('Borders', () => {
+  it('borders', () => {
+    cy.visit('/iframe.html?id=snapshots--borders');
+    cy.get('.border-example', { timeout: 30000 }).should('be.visible');
+    cy.percySnapshot('Borders', { widths: [1440] });
+  });
+
+  it('rounded', () => {
+    cy.visit('/iframe.html?id=snapshots--rounded');
+    cy.get('.border-example', { timeout: 30000 }).should('be.visible');
+    cy.percySnapshot('Rounded', { widths: [1440] });
+  });
+});

packages/documentation/netlify.config.json

@@ -1,4 +1,4 @@
 {
-  "siteId": "916313b9-cc34-4291-bb7f-6463df07598d",
-  "siteUrl": "temp-next-design-system-post.netlify.app"
+  "siteId": "edc7287b-ec63-423c-84aa-c2a1cffbcf87",
+  "siteUrl": "swisspost-design-system-next.netlify.app"
 }

packages/documentation/src/stories/guidelines/accessibility/accessibility.docs.mdx

@@ -1,11 +1,12 @@
 import { Meta } from '@storybook/blocks';
-import * as RegulationStories from './accessibility.stories';
+import * as AccessibilityStories from './accessibility.stories';
+import { Canvas } from '@storybook/blocks';
 
-<Meta of={RegulationStories} />
+<Meta of={AccessibilityStories} />
 
 # Accessibility
 
-<figure>
+<figure className="mb-56">
   <blockquote className="blockquote" lang="de">
     <p className="mb-16">
       Die Postdienste müssen so angeboten werden, dass Menschen mit Behinderungen sie in
@@ -24,3 +25,117 @@ import * as RegulationStories from './accessibility.stories';
     </cite>
   </figcaption>
 </figure>
+
+<div className="light-section pt-8 pb-48">
+## Introduction
+
+Swiss Post is guided by the standards of the Web Content Accessibility Guidelines (WCAG), Level AA.
+
+The Web Content Accessibility Guidelines are a recommendation for designing accessible Internet content. They were developed by the World Wide Web Consortium’s (W3C) Web Accessibility Initiative. The Level AA guidelines set out the following requirements in particular:
+
+  <div className="py-12">
+    <div className="row g-48">
+      <div className="col-md-6">
+        <div>
+          <post-icon name="2114" style={{ fontSize: '64px' }}></post-icon>
+          <div>
+            <h3 className="mt-12 h6">Perceivability</h3>
+            <p>
+              through text alternatives for images, subtitles for audio, ability to display content in
+              different ways and change colour contrasts
+            </p>
+          </div>
+        </div>
+      </div>
+      <div className="col-md-6">
+        <div>
+          <post-icon name="2130" style={{ fontSize: '64px' }}></post-icon>
+          <div>
+            <h3 className="mt-12 h6">Operability</h3>
+            <p>
+              through keyboard operation, colour contrasts, time limits for data entry, prevention of
+              seizures and navigability.
+            </p>
+          </div>
+        </div>
+      </div>
+      <div className="col-md-6">
+        <div>
+          <post-icon name="2165" style={{ fontSize: '64px' }}></post-icon>
+          <div>
+            <h3 className="mt-12 h6">Undestandability</h3>
+            <p>through readability, predictability and assistance with entering data.</p>
+          </div>
+        </div>
+      </div>
+      <div className="col-md-6">
+        <div>
+          <post-icon name="2087" style={{ fontSize: '64px' }}></post-icon>
+          <div>
+            <h3 className="mt-12 h6">Robustness</h3>
+            <p>through compatibility with assistive technologies.</p>
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>
+
+<div className="pt-8">
+## Best practices
+
+Here are some key best practices to follow when designing and developing accessible websites and applications. While these are important starting points, there are many more considerations to ensure full accessibility. For more in-depth guidance, visit the [W3C website](https://www.w3.org/).
+
+### Color contrast
+
+Ensure that text has sufficient contrast against its background. The minimum recommended contrast ratio for text is 4.5:1 for normal text and 3:1 for large text.
+
+<Canvas sourceState="shown" of={AccessibilityStories.Default} />
+
+### Keyboard navigation
+
+Ensure all interactive elements (buttons, links, forms) are accessible via keyboard. This means they should be focusable and navigable using the Tab key. Use `:focus` styles to indicate focus on elements and avoid `tabindex="-1"` unless it’s necessary.
+
+We provide a `.focus-ring` helper class to add a focus style to custom elements. Read more on [our docs](/?path=/docs/6eea4ad2-d5d2-44bf-a7a5-d5621ecd6c36--docs).
+
+Make sure focus is managed properly during dynamic updates or modal windows. For example, focus should be set to the first interactive element inside a modal when it opens and should return to the original trigger when closed.
+
+<Canvas sourceState="shown" of={AccessibilityStories.Focus} />
+
+### ARIA Landmarks
+
+ARIA landmarks are used to identify larger overall sections of the webpage and allow users to quickly navigate sections of the page. Common landmarks include `role="navigation"`, `role="main"`, `role="header"` and `role="footer"`.
+
+### Forms
+
+Ensure that form elements are clearly labeled and use visual indicators such as asterisks for required fields.
+
+Ensure every form field has a properly associated label element and is linked to it using the `for` attribute.
+Use `aria-describedby` for additional descriptions, such as instructions or errors.
+Read more about [form hints](/?path=/docs/43525c38-d00c-4632-8cc5-0fb8a0f2a741--docs) and [form validations](/?path=/docs/1aa900d9-aa65-4ae0-b8cd-e6cca6cc3472--docs).
+
+<Canvas sourceState="hidden" of={AccessibilityStories.FormHint} />
+
+### Alternative text for images
+
+Always provide text alternatives for non-decorative images. This can be in the form of alt text or ARIA labels.
+Ensure images are meaningful and provide relevant context. Avoid using empty `alt=""` for important images.
+
+<Canvas sourceState="shown" of={AccessibilityStories.AltText} />
+
+### Accessible navigation (Skip links)
+
+Implement skip links that allow users to bypass repetitive content and jump directly to the main content. We provide a component to style those skiplinks, which you can read about [on our docs](/?path=/docs/2fc3b456-19ba-4ede-b1bc-499518f829b1--docs).
+
+### Semantic HTML
+
+- Use proper HTML elements to define the structure of the page. This helps assistive technologies (like screen readers) interpret and navigate the content effectively.
+- Use `<h1>` to `<h6>` tags correctly to represent headings. Ensure only one `<h1>` per page (typically the main heading).
+- Use `<article>`, `<section>`, `<nav>`, and `<footer>` to structure content.
+
+### Responsive design
+
+Ensure your design is responsive and adjusts appropriately across different screen sizes. This helps users with low vision or those using screen magnifiers.
+Use flexible grid layouts and ensure the design is functional across all screen sizes. Read more about [responsive design](/?path=/docs/51785576-8553-4909-8827-fd97de4f874e--docs).
+
+</div>

packages/documentation/src/stories/guidelines/accessibility/accessibility.stories.ts

@@ -1,5 +1,6 @@
 import { StoryObj } from '@storybook/web-components';
 import { MetaExtended } from '@root/types';
+import { html } from 'lit/static-html.js';
 
 const meta: MetaExtended = {
   id: '759a427c-7884-474e-b6b7-de32d3acf5df',
@@ -13,4 +14,65 @@ export default meta;
 
 type Story = StoryObj;
 
-export const Default: Story = {};
+export const Default: Story = {
+  render: () =>
+    html`<div class="p-12 my-12" style="color: #050400; background-color: #f0efed;">
+        <p>This text has enough contrast with its background.</p>
+      </div>
+      <div class="p-12 my-12" style="color: #9b9a96; background-color: #f0efed;">
+        <p>
+          This text does not have enough contrast with its background and is not easily readable.
+        </p>
+      </div>`,
+};
+
+export const Focus: Story = {
+  decorators: [
+    story => html`<div class="d-flex flex-column gap-12 align-items-start">${story()}</div>`,
+  ],
+  render: () =>
+    html`
+      <a href="#">This link is accessible using keyboard navigation and has a focus ring.</a>
+      <button class="btn btn-primary">
+        This button is accessible using keyboard navigation and has a focus ring.
+      </button>
+      <button class="btn btn-secondary" tabindex="-1">
+        This button is not accessible using keyboard navigation.
+      </button>
+    `,
+};
+
+export const FormHint: Story = {
+  render: () => html`<div class="form-floating mb-24">
+      <input
+        id="myinput"
+        class="form-control"
+        type="text"
+        placeholder="Placeholder"
+        aria-describedby="form-hint-myinput"
+      />
+      <label class="form-label" for="myinput">Label</label>
+      <p class="form-hint" id="form-hint-myinput">
+        This hint gives additional information on how to fill in the form input.
+      </p>
+    </div>
+    <div class="form-floating">
+      <input
+        id="myinvalidinput"
+        class="form-control is-invalid"
+        type="text"
+        placeholder="Placeholder"
+        aria-invalid="true"
+        aria-describedby="form-validation-myinvalidinput"
+      />
+      <label class="form-label" for="myinvalidinput">Label</label>
+      <p class="invalid-feedback" id="form-validation-myinvalidinput">
+        This message informs that the input field is not valid.
+      </p>
+    </div> `,
+};
+
+export const AltText: Story = {
+  render: () =>
+    html` <img src="/assets/images/logo-swisspost.svg" alt="Swiss Post Logo" class="w-48" /> `,
+};

packages/documentation/src/stories/introduction.styles.scss

@@ -9,30 +9,6 @@ tokens.$default-map: utilities.$post-spacing;
   overflow-x: hidden;
 }
 
-.light-section {
-  position: relative;
-  background-color: post.$light;
-
-  &:before,
-  &:after {
-    display: block;
-    content: '';
-    position: absolute;
-    top: 0;
-    bottom: 0;
-    background-color: inherit;
-    width: 100vw;
-  }
-
-  &:before {
-    right: 100%;
-  }
-
-  &:after {
-    left: 100%;
-  }
-}
-
 .tile-wrapper {
   display: flex;
   flex-wrap: wrap;

packages/documentation/src/stories/misc/migration-guide/shared.component.scss

@@ -22,7 +22,7 @@ migration-global-state {
       margin-left: 2rem;
       padding-bottom: 2rem;
       padding-left: 3rem;
-      border-left: 4px solid post.$light;
+      border-left: 4px solid post.$white;
       min-height: 5rem;
 
       @include post.media-breakpoint-down(sm) {
@@ -48,7 +48,7 @@ migration-global-state {
         left: calc(-2rem - 2px);
         width: 4rem;
         height: 4rem;
-        background: post.$light;
+        background: post.$white;
         text-align: center;
         font-weight: bold;
         font-size: 1.2em;

packages/documentation/src/stories/utilities/borders/borders.docs.mdx

@@ -0,0 +1,52 @@
+import { Canvas, Controls, Meta } from '@storybook/blocks';
+import * as BordersStories from './borders.stories';
+
+<Meta of={BordersStories} />
+
+# Borders & Radius
+
+<div className="lead">
+  Use border utilities to define and style the `border` and `border-radius` of an element.
+</div>
+
+## Border
+
+The `border` utility provides the ability to add, remove, or style borders using predefined classes.
+
+- `border`: Applies a border on all sides of an element.
+
+- `border-{side}`: Sets the border on a specific side. Supports `border-top` (top edge), `border-end` (inline end, mapped to right in LTR), `border-bottom` (bottom edge), and `border-start` (inline start, mapped to left in LTR).
+
+- `border-width`: Defines the border width.
+
+### Examples
+
+#### Add borders to custom elements
+
+<Canvas sourceState="shown" of={BordersStories.BorderSides} />
+<div className="hide-col-default">
+  <Controls of={BordersStories.BorderSides} />
+</div>
+
+#### Remove specific borders
+
+Border subtraction can be achieved with the use of the `border-{side}-0`
+classes.
+
+<Canvas sourceState="shown" of={BordersStories.RemoveBorders} />
+<div className="hide-col-default">
+  <Controls of={BordersStories.RemoveBorders} />
+</div>
+
+## Border Radius
+
+Add the `rounded` class to an element to easily apply a border-radius on its corners.
+
+- `rounded-{side}-{scale}`: Αpplies a border-radius on all or specific sides and defines its scale. Predefined classes for the `side` are: `top`, `end` , `bottom` and `start` and for the `scale` are: `4`: 4px, `8`: 8px, `pill`: 50rem and `circle`: 50%.
+
+### Examples
+
+<Canvas sourceState="shown" of={BordersStories.BorderRounded} />
+<div className="hide-col-default">
+  <Controls of={BordersStories.BorderRounded} />
+</div>