2.0 Requirements

Project

The project refers to the entire framework that generates the library, the website and other documentation

• The project must have a strict division between the library and the website

  • The website does rely on the library, the library has no dependency on the website
  • The library may be updated with no impact on the site, the website may be updated with no impact on the library

• The library styles must be separated from the documentation for easy package consumption.

  • The npm package will distribute the dist and scss directories
  • The website docs will not be packaged

dist (compiled drop-in files)
scss (SASS src)
docs (documentation website)
ops (project tooling)
test (library testing)

• The library version must be easy to identify
  • The compiled and source files should include a comment with the release number
  • The website source should include a comment or cachebusting mechanism, e.g., query param, to identify the version of the library
  • The website should have a unique version number to identify website releases independent of the library.

Package

The package refers to the CSS and other resources used by developers to implement components to create user interfaces.

• Components must be conceived of and built with a data-driven mentality.

  • All dev teams implement component logic by considering the properties and states required to render the component, we must consider the same when building the component.
  • A JSON schema and data file should be available for every component, tests should be written to validate the data against the schema.
  • All components must be tested independently of the website with the full library CSS and with only the component CSS.
  • All HTML examples must be generated with a component architecture, the HTML will be picked up for the documentation.

• All components must use a BEM class notation.

  • Layout and component styles should be a single class (specificity 0-1-0) to allow implementors overriding ease.
  • Nested child selector relationship should be discouraged to avoid higher specificity, when necessary, use be no more than two selectors used to define the relationship and the CSS rules should be targeted and minimal, e.g., .foo--error .bar { color: red; }
  • Modifiers should apply to the element which is being modified not the parent element, e.g., .table-row--stripe { background-color: pink; } not .table--stripe .table-row.
  • SASS linting should be included in the build process to enforce coding standards.

• Theming capabilities must be considered at every step

  • Theming should be considered a customization feature available when using the SASS source.
  • Teams should be able to implement custom breakpoints, colors, type, and spacing with minimal effort
  • Core SASS variables should be global, component SASS variables should be local. A component variable should never be used outside of the component styles.
  • Variables should be descriptive of the application not the style itself, e.g., $tn-card-background-color-disabled not $tn-card-background-color-lightgray.

• Accessibility support must be built-in to the library styles

  • The library should prioritize accessibility attributes for interactive states but should also provide backup classes, i.e., [aria-disabled="true"], .is-disabled { opacity: 0.4; }
  • Accessibility testing should be part of the build process.

• The SASS source will be a robust toolkit for developers

  • The SASS functions and mixins should be useful to build complex UIs on top of the base library.
  • Major and minor modifications should be easy to achieve with minimal side effects.
  • The toolkit must be documented to provide visibility into the technical side of the library.

Website

The website refers to documentation of the library and the design system.

• Each minor and major version of the website must be archived and fully available, esp. 1.5.6

  • An implementor using an older version of the library should be able to view the full documentation for that version.
  • Deprecated functionality must be clearly noted.
  • Release notes should be easily accessibile.

• Component examples must be sourced from a data-driven component architecture

  • Block structures, HTML code, properties, modifiers, and states should be well-considered to emphasize that data in results in predictable rendering.
  • The code examples should be available as HTML with the possibility of additional code examples, e.g., NG, NGX, JSX.
  • Team should be able to contribute technology-specific implementations back to the library.

• Website should use the library from the source

  • The website should take advantage of the toolkit features in the library.
  • Library settings and components should be augmented with documentation specific features.
  • Production website builds should use the distributed library package, not the project source, to enforce the separation.