• Text Element Specification

    Each reusable component can have many layouts and styles. Components are made up of simple elements, like text, images, form inputs, links and various calls to action. Each element can have dozens of configurable items. The example below explores the rabbit holes for an otherwise simple dropdown.

    The seeminingly infinite requirements and specifications are indeed overwhelming. However, years of repeating the same process led me to create the schema for all of it. Once there is a home for everything you know all the questions to ask and you have all the places to put the answers.

    When you hire me you get this level of detail for the dozens of components that build the user journeys your customers want and need.

    Rich Text Element Details

    Rich Text Element Details

    Permutations

    Light Mode or Background

    This is paragraph text using the DM Sans font from Google. This text can be bold, italicized, or underlined, which can all be marked up using the authoring dialog, which is described on the Curation tab.

    Paragraph with Inline Rich Text
    • Defined in typography.css
    • Inline text can be tagged (see Curation)
    • Bullet item 1
    • Bullet item 2
    • Bullet item 3
    Unordered Bulleted List
    • Defined in typography.css
    • Uses standard HTML unordered list (ul) tag
    1. Item No. 1
    2. item No. 2
    3. Item No. 3
    Numbered List
    • Defined in typography.css
    • Uses standard HTML ordered list (ol) tag

    Dark Mode or Background

    This is paragraph text using the DM Sans font from Google. This text can be bold, italicized, or underlined, which can all be marked up using the authoring dialog, which is described on the Curation tab.

    Paragraph with Inline Rich Text
    • Defined in typography.css
    • Inline text can be tagged (see Curation)
    • Bullet item 1
    • Bullet item 2
    • Bullet item 3
    Unordered Bulleted List
    • Defined in typography.css
    • Uses standard HTML unordered list (ul) tag
    1. Item No. 1
    2. item No. 2
    3. Item No. 3
    Numbered List
    • Defined in typography.css
    • Uses standard HTML ordered list (ol) tag

    Annotations

    This is plain text and this is emphasis text, which identifies a shift in focus within a sentence, helping the natural language processing (NLP) algorithms of web crawlerd to more accurately parse the copy's editorial tone and context. accurately. This tag also instructs the screen readers to verbally stress the word (by slightly altering the pitch, volume, or speed of the synthesized voice), preserving the natural verbal cadence of human speech

    Although not commonly used, text can also be underlined

    • Bullet item 1
    • Bullet item 2
    • Bullet item 3
    1. Item No. 1
    2. item No. 2
    3. Item No. 3

    This is plain text and this is emphasis text, which dentifies a shift in focus within a sentence, helping the natural language processing (NLP) algorithms of web crawlerd to more accurately parse the copy's editorial tone and context. accurately. This tag also instructs the screen readers to verbally stress the word (by slightly altering the pitch, volume, or speed of the synthesized voice), preserving the natural verbal cadence of human speech

    Although not commonly used, text can also be underlined

    • Bullet item 1
    • Bullet item 2
    • Bullet item 3
    1. Item No. 1
    2. item No. 2
    3. Item No. 3
    Interactions
    • View only
    CSS

    Bold - apply 'strong' in a span

    Italic - apply 'em' in a span

    Underline - apply 'u' in a span

    Bulleted List - apply li class="list__item" to each line wrapped in ul class="list--unordered-bullet"

    Numbered List - apply li class="list__item" to each line wrapped in ul class="list--ordered-numeric"

    HTML

    Inline text is wrapped in a 'span' tag

    Lists are wrapped in a 'ul' tag

    Headings are wrapped in their HTML tag (h1 ... h4)

    Semantic content is described in another detail page

    Javascript
    • Not required for this element
    System(s) of Record
    • CMS
    SEO / Accessibility
    • Can be tagged as h1...h4 to provide better context
    • The 'strong' tag for bolded text Indicates high value keywords for web crawlers alerts screen readers to announce text with a distinct, heightened inflection, or explicitly announce it as "strong" depending on the user's settings
    • The 'em' (emphasis) tag identifies a shift in focus within a sentence, helping natural language processing (NLP) algorithms to more accurately parse the copy's editorial tone and context. accurately. This tag also instructs the screen readers to verbally stress the word (by slightly altering the pitch, volume, or speed of the synthesized voice), preserving the natural verbal cadence of human speech
    • The unordered list 'ul' tag informs web crawlers and screen readers of a list
    • The ordered list ('ol') tag informs web crawlers and screen readers of a numbered list, thus item 1 gets more weight than items 2- n.
    • Semantic HTML can include date/time, location, price, subject matter (defined in another spec)
    • Text should be self-explanatory, therefore explicit ARIA labeling is not necessary, however, proper tagging provides context to screenreader
    Analytics
    • Not applicable at the element level
    • Most analytics will happen at the page and journey level

    Curation

    HTML Heading
    HTML Heading
    Text Field

    Type: Text Field

    Short form text, used for titles and headlines

    Author can apply bold, italic and underline

    Author can apply semantic html (link to detail page)

    Author can apply html heading, if necessary

    Text Area

    Type: Text Area

    Short form text, used for titles and headlines

    Author can apply bold, italic and underline

    Author can apply semantic html (link to detail page)

    Author can apply html heading, if necessary

    Bold Tag Icon

    Type: Toggle

    Applies the bold tag to selected text

    Italic Tag Icon

    Type: Toggle

    Applies the italic tag to selected text

    Underline Tag Icon

    Type: Toggle

    Applies the underline tag to selected text

    Bulleted List Icon

    Type: Toggle

    Applies bulleted list tags to selected text

    Numbered List Icon

    Type: Toggle

    Applies numbered list tags to selected text

    Inline Link

    Type: Tags

    Pops a modal where author can configure a URL

    URL can be configured to open in a new tab

    Semantic HTML Icon

    Type: Tags

    Applies semantic HTML to selected text

    Details are defined under "Standards"

    HTML Heading Icon

    Type: Toggle

    Applies h1 ... h4 to selected text

    Header tagging depends on SEO relevance

    Backlog

    Jira-1234
    User Story
    Interact with Rich Text
    As a site user I want to interact text content
    Acceptance Criteria
    • User can view rich text content
    Jira-1234
    User Story
    Curate rich text on page
    As an author I want to curate rich text on a page
    Acceptance Criteria
    • Author can access the rich text dialog directly or through a component
    • Author can input text into the text area or text field
    • Author can select text and apply the bold style
    • Author can select text and apply the italic style
    • Author can select text and apply the underline style
    • Author can select text and apply an unordered bulleted list
    • Author can select text and apply a numbered list
    • Author can select text and apply the semantic html
    • Author can select text and apply an html heading
    Jira-1234
    Dev Task
    Presentation layer dev for front-end rich text component
    Design, build and test the HTML and CSS
    Acceptance Criteria
    • HTML and CSS are designed per the UI design spec
    • Code is compiled and unit-tested
    Jira-1234
    Dev Task
    Rich text authoring component
    Modify the OOTB rich text component
    Acceptance Criteria
    • Authoring component includes bold, italic and underline options
    • Authoring component includes list options
    • Authoring component includes semantic HTML options
    • Authoring component includes html heading options
    • Output of authoring component produces JSON content that can be consumed by the presentation layer
    • HTML can present the authoring component's by consuming its JSON output

  • Why Documentation Like This Matters

    You are a product manager supporting multiple sites for your organization. One Tuesday afternoon you start seeing a handful of tickets from your “Website Feedback” link in your site’s footer. They are all about the multi-select dropdown.

    You investigate and find that the checkbox icon is missing. You can still make selections, but there’s a broken image link where the icon should be. You also observe that the up and down arrows are also displaying broken links.

    It’s a visual defect and a poor customer experience.

    Current State: Without This Tool

    In today’s world you would most likely open a support ticket with IT. While you classified it as Critical, you still need to plead your case to the Board. This takes a day. Once you win someone in IT has to isolate the problem. This is very common, even in small organizations.

    You detailed the ticket correctly with Steps to Reproduce, Expected Result, Actual Result, but it still takes them two days to figure it out. They fix the issue, you test it in the staging environment, approve the fix, and wait until the next deployment on Monday.

    Meanwhile, your analytics tell you that 10,347 customers had a broken experience, and you have received over 50 notifications about the issue.

    A conservative estimate of the person-hours required to address this issue would be about $1,000. Additionally, your customers have been enduring a broken experience for a week. This does not reflect well on your brand. It could have been fixed in minutes, very few customers would have been impacted, and your brand would be relatively unblemished.

    Succeeding With This Tool

    Upon confirming the issue you navigate to the Multi-Select Dropdown component in the functional design system. Knowing it’s a presentation layer issue, you click on the Presentation tab and find Annotations F and J, which describe the Deselected and Selected states, respectively, of the Checkbox element.

    You see that both the Deselected and Selected states use the .dropdown-checkbox-wrapper and .dropdown-checkbox CSS classes. They also use an asset called dropdown-controls-sprite.png in the /icons/sprites/ folder of your digital asset manager (DAM).

    The Expand/Collapse icons use the .arrow-container, .arrow, .arrow-container, .arrow-CTA-down, and .arrow-CTA-up CSS classes. However, these also use dropdown-controls-sprite.png.

    In a matter of minutes you have isolated the issue.

    The design system tool links to the form-controls.css file where the CSS classes live, and it links to the /icons/sprites folder of your DAM. You could explore the CSS but you’re highly certain the issue is with the sprite. In the icons/sprites folder you search for dropdown-controls-sprite.png and it’s not there. What now? Next you sort all assets by last updated and at the top of the list there’s a file called asjfdsds.png that was last saved 36 minutes ago. You open it and find the four images that represent your up/down arrows and your selected/deselected checkboxes.

    You’ve solved the case. To resolve the issue you need to rename the file back to dropdown-controls-sprite.png. Immediately you return to the live page where you observed the issue and invoke the multi-select dropdown. Before clicking on it you notice the down arrow is appearing. This tells you that your fix worked. You invoke the dropdown and all the arrows and checkboxes are behaving as expected.

    Meanwhile, there are two more inbox notifications about the broken assets. Using your generic “Web Support” email address, you respond everyone notifying them it has been resolved, asking them to re-test to confirm, and thanking them for reporting the issue. A few respond back saying it looks good, some thank you for following up..

    Superior Outcomes

    With the help of the design system tool you managed to clear a costly issue within minutes of hearing about it. You didn’t need a ticket or a software deployment or a justification for marking it a critical defect. You owned it. This is what digital product managers do.

    Cookie Use
    We use cookies to ensure a smooth browsing experience. By continuing we assume you accept the use of cookies.
    Learn More