Documenting UI Component

Design System Documentation

Abrir chat compartido original

Usuario

Let´s document a UI component.

Design System Documentation

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

Usuario

Link

Design System Documentation

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.

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.

Usuario

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.

Design System Documentation

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.

Variant	Purpose
Inline	Used within blocks of text. They are always underlined to distinguish them from the surrounding text.
Standalone	Used outside of paragraphs and do not have an underline unless hovered over. These can include icons to convey the action or destination.

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

State	Description
Enabled (unvisited)	Default state, indicating a link can be clicked and has not been visited.
Hover	Shows when a user's pointer is over the link, usually changing the color or underlining the text.
Focus	Indicates the link is ready to be activated, often highlighted with a border color of $focus.
Active	Shows when the link is being clicked, typically by changing color or style.
Visited	Indicates a link has been previously clicked.
Disabled	Shows the link is currently inactive and cannot be clicked.

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

Element	Property	Color token
Link	Text color	$link-primary
Link (Focus, Active)	Border color	$focus

Interactive States

State	Element	Property	Color token
Hover	Link	Text decoration	Underline
Focus	Link	Border color	$focus

Sizes

Variant	Size	Text Size
Small	Link	Matches small text size
Medium	Link	Matches default body copy size
Large	Link	Larger than default body copy size

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?

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. | Variant | Purpose | | --- | --- | | Inline | Used within blocks of text. They are always underlined to distinguish them from the surrounding text. | | Standalone | Used outside of paragraphs and do not have an underline unless hovered over. These can include icons to convey the action or destination. | 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 | State | Description | | --- | --- | | Enabled (unvisited) | Default state, indicating a link can be clicked and has not been visited. | | Hover | Shows when a user's pointer is over the link, usually changing the color or underlining the text. | | Focus | Indicates the link is ready to be activated, often highlighted with a border color of $focus. | | Active | Shows when the link is being clicked, typically by changing color or style. | | Visited | Indicates a link has been previously clicked. | | Disabled | Shows the link is currently inactive and cannot be clicked. | ## 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 | Element | Property | Color token | | --- | --- | --- | | Link | Text color | $link-primary | | Link (Focus, Active) | Border color | $focus | ### Interactive States | State | Element | Property | Color token | | --- | --- | --- | --- | | Hover | Link | Text decoration | Underline | | Focus | Link | Border color | $focus | ### Sizes | Variant | Size | Text Size | | --- | --- | --- | | Small | Link | Matches small text size | | Medium | Link | Matches default body copy size | | Large | Link | Larger than default body copy size | ## 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?

Usuario

I need color tokens for all interactive states.

Design System Documentation

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.

State	Element	Property	Color Token
Enabled (unvisited)	Link	Text color	$link-primary
Hover	Link	Text color	$link-hover
Focus	Link, Icon	Border color	$focus
Active	Link	Border color	$active
Visited	Link	Text color	$link-visited
Disabled	Link	Text color	$link-disabled

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!

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. | State | Element | Property | Color Token | | --- | --- | --- | --- | | Enabled (unvisited) | Link | Text color | $link-primary | | Hover | Link | Text color | $link-hover | | Focus | Link, Icon | Border color | $focus | | Active | Link | Border color | $active | | Visited | Link | Text color | $link-visited | | Disabled | Link | Text color | $link-disabled | **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!

Usuario

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

Design System Documentation

HTML

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

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

For an Inline Link within a paragraph:

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

CSS

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

/* Base styles for links */
.link-standalone, .link-inline {
  color: var(--link-primary); /* Assuming --link-primary is defined in your CSS variables */
  text-decoration: none; /* Removing underline by default for standalone links */
}

.link-inline {
  text-decoration: underline; /* Ensuring inline links are always underlined */
}

/* Hover state for both */
.link-standalone:hover, .link-inline:hover {
  text-decoration: underline; /* Adding underline on hover for standalone */
  color: var(--link-hover); /* Change color on hover */
}

/* Focus state for both */
.link-standalone:focus, .link-inline:focus {
  outline: 1px solid var(--focus); /* Focus outline color */
  text-decoration: underline; /* Ensuring visibility when focused */
}

/* Active state for both */
.link-standalone:active, .link-inline:active {
  color: var(--active); /* Color for the active state */
}

/* Visited state for both */
.link-standalone:visited, .link-inline:visited {
  color: var(--link-visited); /* Color for visited links */
}

/* Disabled state for standalone links (if applicable, as inline links typically aren't disabled) */
.link-standalone.disabled {
  color: var(--link-disabled); /* Color for disabled links */
  pointer-events: none; /* Disabling click events */
  text-decoration: none;
}

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.

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 <a href="https://example.com" class="link-standalone" aria-label="Visit example.com - opens in a new tab" target="_blank" rel="noopener noreferrer"> Visit Site <svg class="icon" aria-hidden="true" focusable="false">...</svg> </a> ``` For an **Inline Link** within a paragraph: ```html <p> For more information, visit our <a href="https://example.com" class="link-inline">documentation</a>. </p> ``` ### CSS Defining base styles and state variations for both Standalone and Inline links: ```css /* Base styles for links */ .link-standalone, .link-inline { color: var(--link-primary); /* Assuming --link-primary is defined in your CSS variables */ text-decoration: none; /* Removing underline by default for standalone links */ } .link-inline { text-decoration: underline; /* Ensuring inline links are always underlined */ } /* Hover state for both */ .link-standalone:hover, .link-inline:hover { text-decoration: underline; /* Adding underline on hover for standalone */ color: var(--link-hover); /* Change color on hover */ } /* Focus state for both */ .link-standalone:focus, .link-inline:focus { outline: 1px solid var(--focus); /* Focus outline color */ text-decoration: underline; /* Ensuring visibility when focused */ } /* Active state for both */ .link-standalone:active, .link-inline:active { color: var(--active); /* Color for the active state */ } /* Visited state for both */ .link-standalone:visited, .link-inline:visited { color: var(--link-visited); /* Color for visited links */ } /* Disabled state for standalone links (if applicable, as inline links typically aren't disabled) */ .link-standalone.disabled { color: var(--link-disabled); /* Color for disabled links */ pointer-events: none; /* Disabling click events */ text-decoration: none; } ``` **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.