phase2 / outline

Tooling infrastructure for modern web component development.

OutlineJS

Storybook Hosting

Outline is a both a growing Web Component library as well as a toolkit for building out bespoke design systems for a wide variety of client and personal usages. Outline is based on the latest technologies and tools to help your component authoring experience and facilitate adoption in your organization.

More than a Design System

Outline is much more than just you run of the mill design system. Outline provides an added benefit on top of multiple similar libraries available.

• Outline is a set of components
• Outline is a set of tooling and technology to scaffold design systems for a multitude of projects
• Outline is a set of rules for defining components
• Outline is a set of rules for integrating components
• Outline provides well curated documentation on many complex topics
• Outline grows with internal lessons learned project after project here @phase2.

Outline and Outline design systems are built with many of the following notable tools:

• 
• 
• 
• 
• 
• 
• 

Scaffolding a new Outline project

Outline is organized as a mono-repo and is available to use via NPM Packages and our CLI. The outline-cli simplifies the setup process using pre-defined templates available in the outline-templates package as guides on basic scaffolding of new Outline based projects.

Using NPX (recommended)

This method will load the latest version of the Outline CLI to cache, and prompt you when an update is available. This makes it easier than managing a local version to simply run outline init instead.

npx @phase2/outline-cli init

Global Installation

This method will require manually updating from time to time for the latest updates on your system. If you are using NVM appropriately, any version of node would need this installed. If you are using yarn, you can just install it once globally.

With NPM

npm install -g @phase2/outline-cli
outline init

With Yarn

yarn global add @phase2/outline-cli
outline init

Contributing to Outline

Detailed information regarding how to contribute to Outline development, can be found in CONTRIBUTING.md. Expect this information to be refined soon.

Please see Component Development Guide for information about developing for Outline.

outline's Issues

Fix issues with property reflection and attribute names

Fixes needed for header and column components.

Improve tests for `outline-card`

https://github.com/phase2/outline/tree/next/src/components/base/outline-card

Update Vimeo default video to be Phase2 related

outline/src/components/base/outline-video-vimeo/outline-video-vimeo.stories.ts

Line 16 in ed04891

videoID: `253989945`,

Please use the first video, "Understanding Connected Experiences"
https://vimeo.com/channels/52532/432639001

Alert Component

Requirements

Create an alert component that:

• Has large and small size options.
• Has an optional icon (can be hard coded for now until icon component is created/refined).
• Optional: Has basic style options like 'Warning", "Error" "Success" "Basic" (see below).

Example

• https://designsystem.digital.gov/components/alert/

Accessibility Guidelines

W3.org

Slider Component

We need a slider.
An accessible slider.
Maybe more than one slider?
Inspiration links pending.

Better the documentation on outline-link

Outline-link is one of our more flexible components, and we need better sample code blocks that are better than:

<outline-link
  linkHref="{{ linkHref }}"
  linkRel="{{ linkRel }}"
  linkTarget="{{ linkTarget }}"
>
  {{ defaultSlot }}
</outline-link>

Reduce duplication of the list of character replacements

Would we be able to reduce duplication of the list of character replacements if we ran camelize all the time without checking for a list of characters?

Or, could the logic be grouped together, for example, putting the list of characters and conditional checks inside camelize?

Right now, updates require changes in the camelize function as well as the nameDelimiter array. These two are defined quite far apart in the code and then used in a third place: lines 15, 51, and 78.

Originally posted by @damontgomery in #140 (comment)

Add tests for `outline-accordion-panel`

https://github.com/phase2/outline/tree/next/src/components/base/outline-accordion-panel

Add tests for `outline-list`

https://github.com/phase2/outline/tree/next/src/components/base/outline-list

Accordion Component

Requirement

• Create an accordion component that is accessible called outline-accordion.
• Accordion should have optional flag to have only one open, or many open.

Optional features

• I can set the header to use h1, h2, etc using the outline-header component
• I can set link to an accordion using an Anchor link
  • I can copy the link using the browser

Example(s)

https://designsystem.digital.gov/components/accordion/

Accessibility Guidelines

W3.org
A11y Style Guide

Update static media assets to have a greater variety of shapes/sizes

Currently there are many P2 oriented stock images but they are all the same aspect ratio. This means that if you want a square or wide landscape image you need to upload new ones.

It would be great if there were a variety of image aspect ratios and the file names were clear on what that was (ie square_400-400_headphones.jpg)

Add tests for `outline-swatch` and `outline-swatch-set`

• https://github.com/phase2/outline/tree/next/src/components/base/outline-swatch
• https://github.com/phase2/outline/tree/next/src/components/base/outline-swatch-set

Add tests for `outline-tabs`, `outline-tab-panel` and `outline-tab-group`

https://github.com/phase2/outline/tree/next/src/components/base/outline-tabs

Add tests for `outline-icon`

https://github.com/phase2/outline/tree/next/src/components/base/outline-icon

Make conventional commits more "friendly"

...

View (VRT) Visual Regression Test report while reviewing PRs

As a developer / maintainer, I want to view visual regression tool test reports when reviewing PRs on Github, so that I can tell what has changed.

• I don't want the tools to block PRs

Implementation notes

Can we add both Chromatic / Applitools using the free-for-open-source license so we can try these out as a team and eventually choose one?

These should be pretty easy to add / remove and very quickly useful, so the risk to add / remove should be low.

Discussed on a regular meeting.

Package from Rollup is missing some of the components.

As-is, if we get to a certain size (I added outline-alert and outline-modal), Rollup wants to start chunking stuff and it seems to just toss away some random parts of the code or give an error.

I could test this by searching through the dist/outline.js file and couldn't find strings like outline-alert, but could find outline-link.

I think it has something to do with plugin-multi-entry. https://www.npmjs.com/package/@rollup/plugin-multi-entry

The closest I got was something like,

input: {
    include: [
      'src/components/**/*.ts',
    ],
    exclude: [
      'src/components/**/*.stories.ts',
      'src/components/**/*.css.lit.ts',
    ],
  },
  output: [
    {
      // Modern bundle.
      dir: 'dist',
      format: 'esm',
      entryFileName: 'outline.js',
    },
  ],
  manualChunks: () => 'outline.js',

You can run this with yarn rollup.watch.

But this uses the default name of multi-entry.js even though I've tried setting entryFileName according to the documentation in multiple places.

I'm out of ideas for today, but may be able to try again next week.

Add tests for `outline-accordion`

https://github.com/phase2/outline/tree/next/src/components/base/outline-accordion

`outline-video-youtube` component should use the `lite-youtube` technique

An embedded YouTube video adds on average 2.5MB and slows down page load time.

Instead of loading YouTube iframe, you could display just the YouTube-preview-image + the YouTube-play-icon when the page loads. As soon as the user clicks on it, it switches to the YouTube embed and plays the video.

An existing webcomponent library that already does this is - https://github.com/justinribeiro/lite-youtube

We should implement a similar solution in Outline, to replace the current <outline-video-youtube>

Need to convert this PR description into documentation.

Need to convert this PR description into documentation.

Originally posted by @himerus in #126 (review)

Code Splitting / Lazy Loading

To avoid large bundle sizes, we need to enable the ability to enable code splitting/lazy loading.
Stencil did this with Rollup under the hood so we should be able to accomplish the same.

Button Group

Requirements

Create a basic button group component that:

• Takes pre-rendered instances of outline-button passed into a slot.
• Has basic 'Horizontal', 'Vertical' styling options.
• Meets accessibility standards.

Example

https://designsystem.digital.gov/components/button-group/

Accessibility Guidelines

a11y Style Guide (also look at Tabs info?)
Digital A11Y group role

Notes/Questions

Not sure if we need to have some kind of state/change logic built into this component.
This should be actually simple to just pass in any number of buttons into a slot, and then based on a single property of horizontal/vertical alignment, you can swap CSS.

Add tests for `outline-video-vimeo`

https://github.com/phase2/outline/tree/next/src/components/base/outline-video-vimeo

Add .browserslistrc

Implement a .browserlistrc at the root of the repo. Refer to internal standards proposed in Wiki.

• https://github.com/browserslist/browserslist#browserslistrc

Outline Icons

Incorporate inline icons and generate icon script into Outline

Breadcrumb Component

Requirements

Create a basic breadcrumb component that:

• Takes either a data array to render as links, or passes pre-rendered links into a slot.
• Conforms to accessibility guidelines.

Example

https://designsystem.digital.gov/components/breadcrumb/

Accessibility Guidelines

A11y Style Guide
W3.org

Issues with global watch scripts failing silently

Intro

This fix will need to be back-ported to several internal projects.

I initially setup a simple usage of postcss-cli to watch and compile the global CSS for Storybook that is generated.

However, that doesn't see changes in certain circumstances, and we need something like https://github.com/doowb/watch-cli to do a better job of watching the files we need.

Details

@todo

Port over Icon Generate Script

Update the generate icons script in Outline, and test.

Update list components default styles

I want to update some of this CSS to use @apply where appropriate/possible. This one would simply be @apply flex flex-col;.

I would do this throughout this CSS file, including using some of the demo color palette for the colors.

Originally posted by @himerus in #94 (comment)

Make `_conditionalSlotTemplate` work with default slots

outline/src/components/base/outline-element/outline-element.ts

Lines 52 to 74 in 0929917

	protected _conditionalSlotTemplate({
	elementName,
	slotNameStub,
	wrapperElementType = 'div',
	ariaLabel = null,
	}: {
	elementName: string;
	slotNameStub: string;
	wrapperElementType?: string;
	ariaLabel?: string | null;
	}): TemplateResult | null {
	const namespacedSlotName = `${elementName}--${slotNameStub}`;
	return this.querySelector(`[slot="${namespacedSlotName}"]`) !== null
	? html`<${unsafeStatic(
	wrapperElementType
	)} id="${slotNameStub}" aria-label="${ifDefined(ariaLabel)}">
	<slot
	name="${namespacedSlotName}"
	@slotchange="${() => this.requestUpdate()}"
	></slot>
	</${unsafeStatic(wrapperElementType)}>`
	: null;

While this feature is great for a component with a lot of named slots, our "default" behavior should be on an item with a single slot to leave that slot unnamed, so that the consumer doesn't need to add any wrapper markup with slot="my-named--slot".

I'd like to see this work on unnamed slots.

Refactor outline-tab-group for mobile/accordion switch

As can be seen at https://github.com/phase2/outline/blob/next/src/components/base/outline-tabs/outline-tab-group/outline-tab-group.stories.ts#L85-L97, the mobile version of the tab group becomes an outline-accordion.

Currently this is demonstrated via the consumer, Storybook rather than being a PART of the outline-tab-group itself.
We should assume the tab group relies on the accordion, and we swap them ourselves via the design system, and not rely on the consumer to slot an additional component, that if missing nullifies the current content in the tab panel.

Improve tests for `outline-grid`

https://github.com/phase2/outline/tree/next/src/components/base/outline-grid

Enhancement: Alert

Enhancements for #41.

• Add icons when available
• Add the ability to close alerts.
  • If these might be used to display an alert dynamically after page load we should look into supporting aria-live polite

Pull request references

#60

MDX Stories should be excluded from prettier formatting

The formatting of code inside MDX files is very tricky when it comes to code inside a <Canvas> element.

We need to add *.stories.mdx to .prettierignore.

Conflicting namespaces: ALL_HORIZONTAL_ALIGNMENT

(!) Conflicting namespaces: "virtual:multi-entry.js" re-exports "ALL_HORIZONTAL_ALIGNMENT" from both "src/components/base/outline-container/config.ts" and "src/components/base/outline-element/utils/types.ts" (will be ignored)

The instance in src/components/base/outline-container/config.ts should be removed and instead reference the shared one in outline-element.

Update for static directory declaration

https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#deprecated---static-dir-cli-flag

Improve tests for `outline-image`

https://github.com/phase2/outline/tree/next/src/components/base/outline-image

Fix yarn test on Gitpod

When running yarn test in a GitPod environment, there are a host of errors.

Improve tests for `outline-link`

https://github.com/phase2/outline/tree/next/src/components/base/outline-link

Add tests for `outline-code-block`

https://github.com/phase2/outline/tree/next/src/components/base/outline-code-block

Implement a method (config) to override the color sets available

outline/src/components/base/outline-swatch-set/outline-swatch-set.ts

Line 11 in 3350717

export const swatchSets = ['brand', 'neutral', 'ui', 'demo'] as const;

GitHub Actions publishing to pages not working

The default Storybook package is not updating at outline.phase2tech.com.
https://github.com/phase2/outline/tree/storybook hasn't been updated in 21 days despite pushes to next.

Add tests for `outline-video-youtube`

https://github.com/phase2/outline/tree/next/src/components/base/outline-video-youtube

Implement automated component documentation

Consider wca for implementing a per-component .md file.

Improve tests for `outline-heading`

https://github.com/phase2/outline/tree/next/src/components/base/outline-heading

Test should check almost all possible variants.

Improve tests for `outline-element`

https://github.com/phase2/outline/tree/next/src/components/base/outline-element

Find ways we can test this base component more thoroughly.
Or do all the test for elements that extend outline-element cover this well enough?

Failure of GitLab pipelines after .npmrc was added.

For some reason the code at https://github.com/phase2/outline/blob/next/.gitlab-ci.yml#L75 doesn't seem to work properly when the .npmrc was added in https://github.com/phase2/outline/pull/40/files#diff-e813096d69c49812e40e00be9ac8fa14d77f0ec1f97ab4c45cb096b3bedd35de.

Modal Component

Requirements

Create a basic modal component that:

• Can be closed via button or keyboard (esc key).
• Has small, medium, full screen sizes.
• At this stage passes all content into a slot.
• Meets accessibility standards.

Examples

https://designsystem.digital.gov/components/modal/

Accessibility Guidelines

W3.org

Improve test for `outline-breadcrumb`

https://github.com/phase2/outline/tree/next/src/components/base/outline-breadcrumbs

Documentation: Using Outline in an existing application

What files do you need to import into your application after you run a build of the Outline Design System?

1. dist/outline.js
2. outline.theme.css

I'm not sure where the other dist files come into play but after including the aforementioned files in an existing application (React) I was able to successfully use the base Outline components in my React components