Skip to content

HOWTO.md

Latest commit

 

History

History
205 lines (130 loc) · 6.33 KB

HOWTO.md

File metadata and controls

205 lines (130 loc) · 6.33 KB

Core Styles - How To

Use All of Core Styles

This method expects no other website theme is present. If you must build atop an exisitng theme, then Use Some of Core Styles.

Load stylesheets (as needed) in this order. The Core Styles "Base" is required. A Core-Styles' "Project" is recommended.1

  1. Foundation
  2. Base
  3. Project
  4. Cosmetic

0. Foundation

Optional.

If you want your project to use a reset, normalize, or reboot, then load it first. Please report any compatibility issues.23

If your project uses a full library (e.g. Bootstrap, Ant), then load that library first. Compatibility not yet guaranteed beyond our Bootstrap support.

0. Foundation: Bootstrap

Load Bootstrap and core-styles.bootstrap4.css from a [CDN] in CSS:

@import url("https://cdn.jsdelivr.net/npm/bootstrap@4/dist/css/bootstrap.min.css") layer(foundation);
@import url("https://cdn.jsdelivr.net/npm/@tacc/core-styles@v2/dist/core-styles.bootstrap4.css") layer(foundation);

The use of layer avoids specificity conflicts 45.

0. Foundation: Other

We are also considering support for Ant or ShadCN.

1. Base

Load first core-styles.base.css then any one of these relevant project-type CSS from [CDN] —

stylesheet purpose
core-styles.cms.css marketing or branding sites
core-styles.header.css Core-CMS & Core-Portal
core-styles.docs.css documentation sites
core-styles.portal.css portals (i.e. web apps)

— in CSS:

@import url("https://cdn.jsdelivr.net/npm/@tacc/core-styles@v2/dist/core-styles.base.css") layer(base);
@import url("https://cdn.jsdelivr.net/npm/@tacc/core-styles@v2/dist/core-styles.______.css") layer(base);

Replace ______ with cms, docs, portal, etc.

2. Project

Load global stylesheet(s) specific to your project.

  • Either in HTML:

    <link rel="stylesheet" href="..." />

  • Or in CSS:

    @import url("...") layer(project);

    The use of layer avoids specificity conflicts 45.

3. Cosmetic

Optional

Load stylesheet(s) for variant style of your project.

  • Either in HTML:

    <link rel="stylesheet" href="/your/project/stylesheet.css" />

  • Or in CSS:

    @import url("/your/project/stylesheet.css") layer(cosmetic);

Use Some of Core Styles

For a Portal Application

See https://github.com/TACC/tup-ui/blob/9402505/apps/tup-ui/src/styles/README.md#use-core-styles.

For a CMS or Documentation Site

This method is meant to add support for Core Styles patterns atop an existing theme. If you expect Core Styles to be your theme, then follow Use All of Core Styles instead.

To use only what you need of Core Styles:

  1. Load Settings.*
  2. Load stylesheets as necessary:

* This lets Core Styles patterns access custom properties they assume exist.

Load Settings

Load core-styles.settings.css from a [CDN].

  • Either in HTML:

    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@tacc/core-styles@v2/dist/core-styles.settings.css" />

  • Or in CSS:

    @import url("https://cdn.jsdelivr.net/npm/@tacc/core-styles@v2/dist/core-styles.settings.css");

Load a Core Styles Pattern

To use a pattern as is.

  • Either in HTML:

    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@tacc/core-styles@v2/dist/components/c-message.css" />

  • Or in CSS:

    @import url("https://cdn.jsdelivr.net/npm/@tacc/core-styles@v2/dist/core-styles.settings.css");

Extend a Core Styles Pattern

To use a pattern but also change it to fit a unique requirement of your site.

  • Either in HTML:

    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@tacc/core-styles@v2/dist/components/c-message.css" />
<style>
  .c-message--scope-section {
    margin-bottom: 1em;
  }
</style>

  • Or in CSS:

    @import url("https://cdn.jsdelivr.net/npm/@tacc/core-styles@v2/dist/core-styles.settings.css");

.c-message--scope-section {
  margin-bottom: 1em;
}

(Auxiliary) Core Styles in React

See how Core Styles can be used in React with CSS Modules.

(Internal) Style Guide

To author CSS like is done for Core Styles, follow TACC's CSS Style Guide.

[cdn]: We prefer JSDeliver, because it allows the same syntax for tag, branch, and commit and because its parsing of Semver lets you use @v2 to get the latest release within version 2.

Footnotes

  1. Stylesheet load order and naming comes from MCSS. ↩

  2. Core-Styles testing with a reset, normalize, or reboot has only been atop Bootstrap 4's reboot.scss. ↩

  3. Report as issues in Github. ↩

  4. See developer documentation for specificity. ↩ ↩2

  5. See educational illustration on specificity. ↩ ↩2