diff --git a/deep-dives/best-practices-for-annotating.md b/deep-dives/best-practices-for-annotating.md new file mode 100644 index 0000000..b7e8a75 --- /dev/null +++ b/deep-dives/best-practices-for-annotating.md @@ -0,0 +1,99 @@ +# Best practices for annotating 🏆 + +The best annotation kit is only as useful as it is legible for the people consuming the annotations. Here are our recommended techniques for keeping our documentation easy to read and free of overwhelming clutter. + +> [!TIP] +> 1. When positioning Stamps on top of a design frame, it can be helpful to Lock (**Shift + Command/Control + L** ⇧+⌘/⌃+L) the frame or hold down the **Space** __ key while dragging a component. This helps prevent Stamps being inserted into the design itself which can make them difficult to edit and disrupt the layout of any frames that use auto-layout. +> 2. You don’t need to annotate existing UI that hasn’t been changed in the current work, or is not an immediate part of the new user experience. + +--- + +## Best practice 1: Keep the design frame legible +Try to place stamps outside the frame, with the “pin”, “bracket”, or “lasso” referencing the appropriate design element. + +With closer proximity to associated Detail components in the margins, engineers can quickly scan the annotations and there is less risk of them accidentally overlooking one. + +Keeping the design frame legible also makes the distinction between the original design and our annotations more obvious. This reduces the time and cognitive effort required for folks to understand the documentation. + +| **Less legible** | **More legible** | +|--|--| +| GitHub’s 2025 Universe website homepage. There are 23 annotation stamps overlaid on the design, placed in such a way that it's confusing to figure out what stamp relates to what content, as well as where the annotation stops and the design starts. | The same page with annotation stamps that are not too close to one another, don't overlap, and extend just past the design frame's borders. Annotations are now easily distinguishable, and the underlying design is far less obscured. | + + +--- + +## Best practice 2: Split annotation types on to duplicate frames +Large features and full pages may contain hundreds of elements to annotate. Putting every type of annotation on only one frame can make it become visually overwhelming and difficult to parse. + +One strategy to help keep things legible is to duplicate the page/frame and place only one or two types of annotation on each. This also helps ensure there is room around the design to place annotations in a legible way, as described in best practice #1. + +In this example, we have split one fully annotated design into two, with Focus Order annotations on their own dedicated frame. + +| **Before** | **After** | +|--|--| +| GitHub’s 2025 Universe homepage on mobile in portrait orientation. There are annotation stamps for links, buttons, images, focus order, and headings. All combined, it appears a bit like someone sneezed a lot of confetti on top of a design frame. | The same design, duplicated into two frames. The frame on the right has all of the focus order annotation stamps, while the frame on the left has everything else. | + +--- + +## Best practice 3: Deeplink stamp labels with details +Linking a Details annotation to its corresponding Stamp can be helpful for helping people understand which Stamp is associated with which Details instance. This can be especially useful for complicated annotations, or situations where the Stamp and its corresponding label are visually separated. + +To deep-link a Stamp label with its corresponding label: + +1. Select the Details annotation instance. +2. Press **Command/Control + L** ⌘/⌃+L to copy the Details instance’s URL to the clipboard. Figma will display a badge notification to communicate that the URL was successfully copied. +3. Click on the text of the corresponding Stamp label until it is highlighted. +4. Press **Command/Control + K** ⌘/⌃+K. +5. Figma will open a command palette menu, with the “Create link” option selected. Press **Return** ⏎ to activate this option. +6. A tooltip menu will pop up over the selected Stamp label text, with a placeholder that reads, “Type or paste a URL”. +7. Paste the Details annotation instance’s URL into the tooltip by pressing **Command/Control + V** ⌘/⌃+V. Then press **Return** ⏎ to add the link. +8. The Stamp text will become underlined, confirming the link has successfully been added. + + +| **First copy the detail instance URL** | +|--| +| A process flow with three steps. Step one shows a detail instance in a selected state. Step two shows a Command plus L keyboard shortcut combination. Step three shows a badge that reads, Page link copied to clipboard. | + +| **Then create a link to the detail instance** | +|--| +| A process flow with eight steps. Step one shows a button stamp instance. Step two shows the stamp in a selected state, with a cursor clicking on the stamp’s text label. Step three shows the stamp’s text label in a selected state. Step four shows a Command plus K keyboard shortcut. Step five shows a Figma command palette, with the “Create link” option selected. Step six shows a tooltip placed over the stamp’s selected text label, with a placeholder value that reads, Type or paste a URL. Step seven shows a Command plus V keyboard shortcut. Step eight shows the stamp again, with a text underline added to the stamp’s text label. | + + +--- + +## Best practice 4: Annotate only what is needed +Designs often have repeated elements, such as a list of social media links. If there’s no variation for each repeated element, you may not need to annotate every single instance. Instead, you can annotate the first one and make a note of this. + +This may also be the case with design treatments across multiple viewports. Many annotations might be the same regardless of viewport size or orientation. In this case, you may not need to annotate it more than once. + +> [!TIP] +> It’s best to communicate this intentional choice to engineering partners to avoid confusion. + +| **Before** | **After** | +|--|--| +| The footer section of the GitHub 2025 Universe website, shown at a mobile breakpoint. There are seven linked social media icons in a row. Each icon has a numbered image and link annotation stamp associated with it, which covers part of the design. To the left and right of the footer are Detail annotations for each stamp, each which has only a small amount of difference in content. These take up a lot of room visually. | The same footer design for the GitHub 2025 Universe website. Now the entire row is selected with a lasso stamp. Only one icon inside the selection has an image and link stamps pointing to it. The corresponding three detail annotations instruct the reader to use each social media service’s name as the accessible name for the SVG icon, which is then used as each link’s accessible name. The overall experience is a lot less visually noisy. | + +--- + +## Best practice 5: Annotate complex components separately +The complexity of an interface is not always distributed equally. When annotating parts of a design that are more dense, there may be a lot of overlap between Stamps. There may also be more detail to a component than there is surrounding space to annotate it clearly. + +This can be addressed in a couple of ways: + +1. Annotating complex patterns in their own frames. Here you can break a design down into smaller, more focused parts to keep things focused and more legible. +2. Using the Area out of scope utility annotation to cover parts of a page that are not relevant. This will provide more space to annotate complex sections, as well as focus attention on the parts that are relevant. + + +A GitHub.com issues page with extensive annotations for images, links, buttons, headings, and form elements. The page's header, navigation, footer, and all but one Issue in the list have been obfuscated by a semi-transparent blue overlay to indicate that these parts of the annotated design are out of scope or redundant. + +--- + +## Best practice 6: Split up complex components into separate screens + +GitHub is full of complex interfaces, including patterns nested inside of other patterns. This can add additional risk, especially in terms of things like accessibility and keyboard navigation. + +It’s helpful to break complex patterns down into smaller pieces when documenting designs. This will help convey vital information to engineers. + +For example, nested lists that contain multiple interactive items are found in many places on GitHub. There are separate annotations for the header at the top of the container, the component’s container, as well as the list item itself. There are also annotations to convey focus order and keyboard navigation through several flows (not all of these are shown here). + +A complex set of annotation frames for our list views component, which has been broken up to make annotations clearer. One frame just shows annotations for the component's container itself. Another has the annotations for the row of actions at the top of the component. Another contains annotations for the content structure of the list items. A fourth shows detailed focus order annotations for the whole component. diff --git a/tutorials/table.md b/tutorials/table.md new file mode 100644 index 0000000..153705c --- /dev/null +++ b/tutorials/table.md @@ -0,0 +1,171 @@ +# How to: Table + +A table is a 2-dimensional data structure where rows and columns are used to represent data about a specific item. Present information in a grid with columns or rows to give quick access to tabular data to help people more easily understand complicated information relationships. + +## Why? + +Tables help people more easily understand complicated information relationships. When constructed properly, they also enable people who use assistive technology to quickly and efficiently navigate and understand the relationship between a table’s columns, rows, and the information placed within each cell. +- All table content must be shown at every screen size. Convey responsive behavior with a Table Details annotation. +- Screen readers have difficulty parsing tables with merged rows and columns. +- Try to keep one discrete piece of information per table cell. + +## Table Stamps and Details + +### [Annotation Tiers](https://github.com/github/annotation-toolkit/blob/main/deep-dives/tiered-model.md) +- Difficulty Tier 3: **Advanced** +- Priority Tier 3: **Nice to have** + +A row of four annotations components: The first is a maroon pin stamp with a label of <table> and a note number set to 1. The second is a maroon bracket stamp with a label of <thead> and a note number set to 2. The third is a maroon lasso stamp which has a white and maroon dashed outline attached to it, a label of <tbody>, and a note number set to 3. The last annotation is a Table Details component with a note number set to 4. It is a white rectangular panel with maroon accents and information about the table HTML element, reflow behavior preference set to horizontal overflow, and a link to the accessibility considerations for that preference. + +### Elements + +#### Table container `` + +Defines a data table, organized into columns and rows. Required. Tables must include: a caption, at least two rows, and at least two columns. +- **Reflow type**: Specifies responsive behavior for the entire table. + - `Horizontal overflow`: Table columns are viewed by scrolling horizontally. Useful for tables that have a lot of columns. + - `Columns become rows`: Table columns are turned into rows, to avoid horizontal scrolling on narrower viewports. + - `No responsive behavior`: Table does not adapt responsively. *Warning: This may have accessibility issues!* + +A table pin annotation and a table details annotation with note numbers set to 1. The table details contains the text Reflow type: Columns become rows. + +#### Caption `` + +Groups header rows that describe the columns of the table. Required. +- **Sticky head**: Indicates the table header row sticks to the top of the viewport when scrolled past. + +A pair of table head pin annotations and table head details annotations with both note numbers set to 3. One details annotation sticky position is toggled OFF, and the other is toggled ON. + +#### Table header `` must be `` + +Groups the main data rows of the table together. + +A table body pin annotation and a table body details annotation. The note numbers are set to 5. + +#### Table row `` + +Represents a horizontal row of cells. +- **Expandable**: Indicates if the table row’s content can be `collapsed` or `expanded`, as well as the state it defaults to. + +A pair of table row pin annotations and table row details annotations. The note numbers are set to 6. One details panels Expandable toggle is OFF, the other is toggled ON, and contains the text This is an expandable row with the default state set to expanded. + +#### Table body cell `` + +Groups rows concluding the table content. A table footer is optional, only use it if your content needs it. +- **Sticky footer**: Indicates the table footer row sticks to the bottom of the viewport when scrolling. + +A pair of table footer pin annotations and table footer details annotations. The note numbers are set to 8, and one details annotation sticky position is toggled OFF, and the other is toggled ON. + +#### Column group `` + +Defines a group of one or more columns for styling or structural purposes. This element is typically not needed, and its inclusion may interfere with some screen readers. +- `span`: Specifies the number of columns the grouping contains. Spanning starts on the first table column and extends the same number of columns as the `span` number used. `span` cannot be used if one or more `` are also used. + +A table column group pin annotation and a table column group details annotation. The note numbers are set to 9, with the span set to 2. + +#### Column `` + +Represents a single column’s definition, used for styling or width control. This element is typically not needed, and its inclusion may interfere with some screen readers. +- **Columns span**: Specifies the number of columns the column element spans. Spanning starts on the first table column and extends the same number of columns as the span number used. + +A table column pin annotation and a table column details annotation. The note numbers are set to 10, with the span set to 2. + +### How to use these annotations + +1. ​Add a **❖ Table Stamp component** from the asset panel. Place the stamp over the design frame and resize to extend pin, bracket, or lasso. Configure the component properties as needed: + - **Label position**: Set based on Stamp’s placement relative to the element being annotated. + - **Show number**: Toggle off if there’s no need for a matching Details annotation (in which case, skip step 2). + - **Note number**: Set this number in relative sequence with the other numbered Stamps placed over the same design. + - **Element**: Select the corresponding element to ensure the Stamp is paired and labelled correctly. + +A table pin annotation and a Figma properties panel. The note number has been set to 3, with the label positioned to the left. + +2. ​Place a ❖ Table Details component in the margins next to the design and configure the component properties as needed: +Element: Select the applicable table element. +Show guidance: Toggle high-level guidance and resources. +Note number: Set this to match the corresponding ❖ Table Stamp. This number should be unique and in relative sequence with other Details annotations on the same design. + +A table details annotation and a Figma properties panel. The note number has been set to 3 and responsive behaviour has been toggled on, with the reflow type property set to horizontal overflow. + +## Table structure + +Proper table structure is essential for presenting data in a clear and meaningful way. Tables without proper structure can be confusing or unusable for users who rely on screen readers, compromising both accessibility and the clarity of the data being presented. + +### [Annotation Tiers](https://github.com/github/annotation-toolkit/blob/main/deep-dives/tiered-model.md): +- Difficulty Tier 3: **Advanced** +- Priority Tier 3: **Nice to have** + +### How to use these annotations + +Place a ❖ Table Structure component in the margins next to the design and configure the component properties as needed: + +1. Toggle the **Show guidance** property if the additional high level guidance and resources aren’t needed. +2. Optionally update the **Title** field. This can help differentiate annotations when multiple tables are used in a single design. +3. Optionally use the **Show description** property to add a description for the table structure itself. +4. Configure the table structure to include all elements. + 1. Select the appropriate **Table element** for the content and place within the table hierarchy. + 2. Select the appropriate **Nesting level**. Each table structure item must be appropriately nested. + 3. Provide a **description** for each item if more context is needed. + 4. For certain elements, there are property toggles to convey when an item may be **sticky**, **sortable**, or **visually hidden**. + +> [!NOTE] +> **You can safely detach this component!** If you need more rows than are included by default in order to show the table structure, you can add more by detaching the component (**⌥⌘B**). Then you can duplicate the **Table structure item** rows. + + +A table structure annotation includes the necessary table markup. Positioned next to this annotation is the visible guidance section, which offers tips such as: All table content must be visible at every screen size… Keep one discrete piece of information per table cell. This guidance also provides relevant references for further support. + +--- + +## Design considerations + +- Does the table caption succinctly describe the table’s purpose? +- Can all of the table’s information be read on narrower viewports? +- Are the table rows and columns clearly communicated visually? +- Does each column and row header have a succinct title? +- Does each table cell have straightforward information? If not, can it be broken out into new columns? +- Are sorting functionality and current sorted state easy to understand? +- Is the data in each column aligned in a way that makes it easier to visually scan? + +## Resources + +- [Tables Tutorial - W3C WAI Tutorials](https://www.w3.org/WAI/tutorials/tables/) +- [HTML table accessibility - MDN](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Structuring_content/Table_accessibility) +- [Table Pattern - ARIA Authoring Practices Guide (APG)](https://www.w3.org/WAI/ARIA/apg/patterns/table/) +- [How To Architect A Complex Web Table - Smashing Magazine](https://www.smashingmagazine.com/2019/02/complex-web-tables/) +- [Web Typography: Designing Tables to be Read, Not Looked At - A List Apart](https://alistapart.com/article/web-typography-tables/) +- [Designing Tables for Reusability - UX Collective](https://uxdesign.cc/designing-tables-for-reusability-490a3760533) +- [Designing a complex table for mobile consumption (nom) - UX Collective](https://uxdesign.cc/designing-a-complex-table-for-mobile-consumption-nom-7472f7b11fe6) +- [A Responsive Accessible Table - Adrian Roselli](https://adrianroselli.com/2017/11/a-responsive-accessible-table.html) +- [Under-Engineered Responsive Tables - Adrian Roselli](https://adrianroselli.com/2020/11/under-engineered-responsive-tables.html) +- [HTML Table Element Guide - CSS Tricks](https://css-tricks.com/complete-guide-table-element/)
` + +Provides a unique and succinct description or title for the table’s content. Important for helping people who use screen readers quickly understand the table’s purpose. Required. +- **Visually hidden**: using a visually hidden caption ensures that the table’s purpose is still conveyed to screen reader users who can't see the screen. If the text is hidden, be sure to fill out the **caption text** field. + +A pair of caption pin annotations and caption details annotations with both note numbers set to 2. One details annotations visually hidden switch is toggled OFF, and the other is toggled ON. + +#### Table head `
` + +Identifies a header cell, which labels the cells being scoped. All cells in a table’s `
` elements with a scope of col. If a table uses row headers: the first cell must be a `` element with a scope of row; the other cells are `` elements. +- **Scope**: Defines the table cells that the table header cell relates to. This can be set to `row`, `col`, `rowgroup`, or `columngroup`. +- **Sortable**: Indicates if the table column’s data can be sorted, as well as **sort order** (`ascending` or `descending`). Can also optionally specify **sort priority** if the table can be sorted by multiple columns at the same time. +- **Advanced mode**: Additional options that may be needed in complex use cases. + - **Element ID**: Specifies an id value for the table header cell. Useful for complicated table layouts. + - **Headers**: A list of space-separated strings corresponding to the id values of the `` elements that provide the headers for this header cell. + - **Colspan**: How many columns the header cell spans across. + - **Rowspan**: How many rows the header cell spans across. + +A pair of table header pin annotations and table header details annotations, both note numbers are set to 4. One details panel Advanced mode is toggled OFF, and the other is toggled ON, and contains multiple fields, including scope which is set to Col, sort order which is set to ascending, colspan and rowspan with a value of 2. + +#### Table body `
` + +Contains a data cell within a table. +- **Advanced mode**: Additional options that may be needed in complex use cases. + - **Element ID**: Specifies an id value for the table cell. Useful for complicated table layouts. + - **Headers**: A list of space-separated strings corresponding to the id values of the `` elements that provide the headers for this cell. + - **Colspan**: How many columns the cell spans across. + - **Rowspan**: How many rows the cell spans across. + +A pair of table body cell pin annotations and table body cell details annotations. The note numbers are set to 7. One details panels advanced mode is toggled OFF, the other is toggled ON, and contains ID, headers, colspan and rowspan fields. + +#### Table footer `