This is a frontent library designed and built for use in Iowa State University web projects.
- Staging site: staging2.idfive.com, currently displaying the master branch. Use
guest/guestfor username/password. - Repo: Bitbucket private.
- Build pipelines: Buddy, idfive access only.
Whenever possible, we reccomend using composer to install this library, to ensure all future updates can be pulled in to your project.
composer require iastate/frontend-component-library
In general, to use this library in your own project, you would need to link the CSS/JS files from the build folder:
- Link to
/build/css/index.css - Link to
/build/css/print.css(print syles only) - Link to
/build/js/index.js
You can then pull, and utilize the provided markup examples in your own project.
This library is designed to be used "as-is" for most developers. If you wish to modify this library, you will need to create your own fork. This section is strictly information for those working on, and committing to, this project.
The component library includes Fractal for component based development. Your own components can be added to the src/components folder. Static assets such as JavaScript, CSS and images will be served out of the build folder, but can also be configured to your specific needs by editing the fractal.js file. For more information, read the fractal guide.
- Installed Boostrap 5.1, the site uses the default breakpoints
- Using Iowa State color variables
- Using Iowa State Font Awesome for social media icons and various elements
- All CSS/JS is scoped to not interfere with Boostrap, using a prefix of "iastate22-" on relevant classes
- All components live in the
src/componentsdirectory - The page structure can be found in
src/components/_page-preview.twig. For individual components, the structure is located insrc/components/_preview.twig
Dependencies need to be installed with node/npm, and is best pinned to stable versions via nvm. More on node usage at idfive.
cd idfive-component-librarynvm usenpm install
To start the fractal development server:
cd idfive-component-librarynvm usenpm run fractal
To build your code for production, prior to a release, run the following:
npm run buildnpm run fractal:build
This will generate build and fractal folders at the root of your project. The build folder contains all of your compiled assets (CSS, JavaScript etc.), while the fractal folder contains a static generated version of your Fractal component library, which can be used for previews and an online reference to your component library. The build folder is committed, in order that projects may use it as a dependency directly.
Releases for this project should follow Semantic Versioning.
Steps when releasing:
- Commit (or merge) and push master to origin.
- Tag
1.0.1(the new release version), and push to origin. The tag is what composer uses to define a new release.
- Written using Twig templates
- Proper ARIA functionality is used to meet WCAG accessibility guidelines
This structure below shows the overall wrappers and ordering needed to properly display the layout:
<body>
<a class="skip-link" href="#main-content">Skip To Main Content</a>
<div class="off-canvas">
<div class="max-bound">
{% include "@site-header" with header %}
<main id="main-content">
{{ yield }}
</main>
{% include "@site-footer" with footer %}
</div>
</div>
<!-- Scripts Here -->
</body>- The
.skip-linklink is provided for accessibility purposes - The
.off-canvasdiv is in use to setoverflow-x: hidden;on the whole page to prevent unwanted horizontal scrolling - Next is the
.max-bounddiv, which provides a max-width, (and 100% width), centers the content and provides a background-color the the whole document - Next our main site header is added
{% include "@site-header" with header %} - Then the
<main id="main-content">is added which contains all of the page content{{ yield }} - After the closing
<main>tag, the footer is added{% include "@site-footer" with footer %} - Kitchen sink pages have an additional tag
<div class="outer-pad">directly after<main>, which provides left and right padding for the page
All images should be added to src/images which compiles to build/images/*.
- All CSS/JS/Images will be compiled from
src/*. - All CSS to be written as SCSS, and compiled via Webpack.
- All CSS compiled from
src/scss/index.scss - All theme JS is written as TypeScript, and compiled to stable, browser-compliant JS via Webpack.
- ALL JS to be compiled from Typescript in
src/js/index.ts
- In
_base.scss,.align-left,.align-right, and.align-centerhandle images placed in WYSIWYG sections - In
_base.scss, the.skip-linkclass is for the "Skip To Main Content" button for accessibility - In
_placeholder-selectors.scss,.visible-for-screen-readersis used to hide content but allow it to be accessibly read/spoken - In
_placeholder-selectors.scss,.outer-pad-xhandles horiztonal padding throughout various parts of the site - In
_placeholder-selectors.scss,%responsive-imgis a placeholder selector which sets up object-fit for images and the padding-top percentage for the associated pseudo element which sets the height of the image - In
_placeholder-selectors.scss,.captionis a re-used type style for image and video captions - In
_placeholder-selectors.scss,.arrowis the arrow shape used throughout various button and nav styles - In
_base.scss, there are two helper classes for remove the space above and below paragraph widgets..paragraph-widget-no-margin-bottomwill reduce themargin-bottomof the widget to zero and.paragraph-widget-no-margin-topwill reduce themargin-toptop zero. These both have!importanttags attached to ensure there are no conflicts.
- W3C Validation
- Passes Accessibility check using WAVE and Google Lighthouse
- Provides fallback of full content for non-JS users.