Let´s document a UI component.

Please name the UI Component you'd like to document.

Link

To create a comprehensive documentation for the Link component, let's gather some detailed information. Could you please provide the following details?

• Description of the Link's visual design and elements.
• Key functionalities and features of the Link.
• Variations or customization options available for the Link.

Link color is link-primary (this also applies to icons in links). Border color for Focus and Active is focus. Two types: Standalone and Inline. Standalone has no underline (only when hovered), Inline links behave the same as standalone links but include an underline. An appropriate icon can be used with standalone links to convey the destination. There are three size variants for the link component: small, medium, and large. Inline link sizes should match the text size they are inline with. Standalone link sizes should match the default body copy size of the page. The list has six main states – enabled (unvisited), hover, focus, active, visited, and disabled. Links can be grouped horizontally or vertically.

Based on the details you've provided, let's structure the documentation for the Link component.

Link

Links are interactive text elements that allow users to navigate to another location when clicked. They can be used for navigation within a page, to other pages within a site, or to external sites.

Overview

Links are crucial for creating a connected experience across the internet, enabling users to easily move from one piece of content to another. They are essential for web navigation, SEO, and providing a good user experience.

When to use

• Navigating the user to a different page or site.
• Downloading files.
• Linking to internal sections of a page (anchors).
• When you want to provide quick access to related information without navigating away from the current task.

When not to use

• If the action does not navigate to another page or location. Consider buttons for actions that do not involve navigation.
• For primary actions on a page, such as submitting a form.

How to use

• Use Inline links within paragraphs or sentences where the link is part of a longer text. They are underlined to stand out from the surrounding text.
• Use Standalone links for more prominent links, typically found outside of paragraphs. These links are not underlined by default but will display an underline on hover to indicate clickability. An icon may accompany standalone links to indicate the action or destination.

Types or Variants

Links come in two types: Inline and Standalone, with three size variants: small, medium, and large.

Sizes for Inline links should align with the text size they accompany, while Standalone link sizes should be consistent with the default body copy size of the page.

Formatting

• Color: The link color is defined as $link-primary. This applies to both the text and any icons used within links.
• States: Links have six states: enabled (unvisited), hover, focus, active, visited, and disabled. The border color for Focus and Active states is $focus.
• Grouping: Links can be grouped either horizontally or vertically to categorize or organize navigational options efficiently.

Content

• Ensure the link text clearly describes the destination or action, providing users with the expectation of what happens next.
• For Standalone links with icons, choose an icon that accurately represents the link's action or destination.

Behaviors

Interactive States

Accessibility

• Use descriptive text for links to ensure clarity for screen reader users.
• Ensure that the Focus state is visually distinct to aid keyboard navigation.
• Consider providing an aria-label for links with icons but no text to describe their purpose or destination.

Style

Color

Interactive States

Sizes

Code

Provide a sample HTML structure for a standalone and inline link, including ARIA roles where applicable.

Summary

Links are a fundamental part of the web's navigational structure, allowing users to seamlessly move between resources. By adhering to best practices in design, behavior, and accessibility, links can significantly enhance user experience, guiding them intuitively through your digital space.

Documentation Finalization

This documentation outlines the primary considerations for implementing accessible and user-friendly links. It covers their types, usage guidelines, styles, and states, ensuring developers and designers have the information needed to effectively use this component.

Would you like to add or modify any sections of this documentation?

I need color tokens for all interactive states.

To document the color tokens for all interactive states of the Link component comprehensively, let's define the specific color tokens for each state based on the initial details you provided. I'll infer the tokens for states that weren't explicitly mentioned but are standard for links.

Style

Color

The base color for the Link component is defined by the color token $link-primary. This color applies to the text and icons within links.

Interactive States

Here, we'll outline the color tokens for each interactive state of the Link component. Since the exact color tokens for some states like hover, visited, and disabled were not provided initially, I'll propose standard practices for these.

Note: The link-hover, link-visited, and $link-disabled tokens are placeholders for the actual color values. You should replace these with the specific color tokens defined in your design system for consistency.

This detailed breakdown provides a clear guide for developers and designers to apply consistent styling across different states of the Link component, ensuring a cohesive user experience. The use of specific color tokens for each state enhances the visual feedback provided to users as they interact with links, contributing to a more intuitive navigation.

If you have specific color tokens for the hover, visited, and disabled states, or if there are any other adjustments needed, please let me know!

Provide sample HTML and css structure for a standalone and inline link, including ARIA roles where applicable.

Below are sample HTML and CSS structures for creating standalone and inline links, including ARIA (Accessible Rich Internet Applications) roles and attributes where applicable to enhance accessibility.

HTML

For a Standalone Link with an icon indicating it's an external link (assuming an SVG icon for demonstration):

html
DownloadCopy code
1<a href="https://example.com" class="link-standalone" aria-label="Visit example.com - opens in a new tab" target="_blank" rel="noopener noreferrer">
2  Visit Site
3  <svg class="icon" aria-hidden="true" focusable="false">...</svg>
4</a>

For an Inline Link within a paragraph:

html
DownloadCopy code
1<p>
2  For more information, visit our <a href="https://example.com" class="link-inline">documentation</a>.
3</p>

CSS

Defining base styles and state variations for both Standalone and Inline links:

css
DownloadCopy code
1/* Base styles for links */
2.link-standalone, .link-inline {
3  color: var(--link-primary); /* Assuming --link-primary is defined in your CSS variables */
4  text-decoration: none; /* Removing underline by default for standalone links */
5}
6
7.link-inline {
8  text-decoration: underline; /* Ensuring inline links are always underlined */
9}
10
11/* Hover state for both */
12.link-standalone:hover, .link-inline:hover {
13  text-decoration: underline; /* Adding underline on hover for standalone */
14  color: var(--link-hover); /* Change color on hover */
15}
16
17/* Focus state for both */
18.link-standalone:focus, .link-inline:focus {
19  outline: 1px solid var(--focus); /* Focus outline color */
20  text-decoration: underline; /* Ensuring visibility when focused */
21}
22
23/* Active state for both */
24.link-standalone:active, .link-inline:active {
25  color: var(--active); /* Color for the active state */
26}
27
28/* Visited state for both */
29.link-standalone:visited, .link-inline:visited {
30  color: var(--link-visited); /* Color for visited links */
31}
32
33/* Disabled state for standalone links (if applicable, as inline links typically aren't disabled) */
34.link-standalone.disabled {
35  color: var(--link-disabled); /* Color for disabled links */
36  pointer-events: none; /* Disabling click events */
37  text-decoration: none;
38}

Note:

• var(--link-hover), var(--focus), var(--active), var(--link-visited), and var(--link-disabled) are placeholders for the actual color values defined in your CSS variables. Replace these with your specific color tokens.
• The aria-label in the standalone link example provides additional context for screen readers, especially for indicating the action of opening in a new tab.
• aria-hidden="true" and focusable="false" on the SVG icon ensure that it is hidden from screen readers and not focusable by keyboard navigation, as its decorative or supplementary to the text which conveys the essential information.
• The rel="noopener noreferrer" attribute on external links improves security and performance when opening links in a new tab.

This setup aims to provide a solid foundation for accessible and visually consistent links within your applications, ensuring both usability and compliance with web accessibility standards.