Kalastatic

Styleguide and Component Library Demo

About this Styleguide

This is an example of what a styleguide can look like with Kalastatic. Note that even though you can have a demo styleguide created when installing Kalastatic, it is assembled with normal components that use the Kalastatic site generator, and the design and functionality can be customized as needed to meet your own project's needs.

Colors

The palette of colors that are used throughout this site.

Sample
--color-grey-10: #333333;
--color-grey-20: #595959;
--color-grey-30: #707070;
--color-grey-80: #e6e6e6;
--color-grey-90: #f9f9f9;
--color-white: #ffffff;
--color-blue-30: #0077aa;
--color-red-20: #ab0000;
Sample Twig 
<div style="padding: 1em; margin: 1em 0; color: var(--color-grey-90); background: var(--color-grey-10);">
  --color-grey-10: #333333;
</div>

<div style="padding: 1em; margin: 1em 0; color: var(--color-grey-90); background: var(--color-grey-20);">
  --color-grey-20: #595959;
</div>

<div style="padding: 1em; margin: 1em 0; color: var(--color-grey-90); background: var(--color-grey-30);">
  --color-grey-30: #707070;
</div>

<div style="padding: 1em; margin: 1em 0; color: var(--color-grey-10); background: var(--color-grey-80);">
  --color-grey-80: #e6e6e6;
</div>

<div style="padding: 1em; margin: 1em 0; color: var(--color-grey-10); background: var(--color-grey-90);">
  --color-grey-90: #f9f9f9;
</div>

<div style="padding: 1em; margin: 1em 0; color: var(--color-grey-10); background: var(--color-white);">
  --color-white: #ffffff;
</div>

<div style="padding: 1em; margin: 1em 0; color: var(--color-grey-90); background: var(--color-blue-30);">
  --color-blue-30: #0077aa;
</div>

<div style="padding: 1em; margin: 1em 0; color: var(--color-grey-90); background: var(--color-red-20);">
  --color-red-20: #ab0000;
</div>
SCSS 
:root {
  --color-grey-10: #333333;
  --color-grey-20: #595959;
  --color-grey-30: #707070;
  --color-grey-80: #e6e6e6;
  --color-grey-90: #f9f9f9;
  --color-white: #fff;
  --color-blue-30: #0077aa;
  --color-red-20: #ab0000;
}

body {
  background: var(--color-grey-90);
}

a {
  &, &:hover {
    color: var(--color-blue-30);
  }
}

Typography

The six levels of headings and paragraph text styles.

Sample

What is Lorem Ipsum?

What is Lorem Ipsum?

What is Lorem Ipsum?

What is Lorem Ipsum?

What is Lorem Ipsum?
What is Lorem Ipsum?

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt.

Sample Twig 
<h1>What is Lorem Ipsum?</h1>

<h2>What is Lorem Ipsum?</h2>

<h3>What is Lorem Ipsum?</h3>

<h4>What is Lorem Ipsum?</h4>

<h5>What is Lorem Ipsum?</h5>

<h6>What is Lorem Ipsum?</h6>

<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>

<p>Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt.</p>
SCSS 
@import url('https://fonts.googleapis.com/css2?family=Source+Sans+Pro:ital,wght@0,400;0,700;0,900;1,400;1,700&display=swap');

:root {
  // Common styles across all the headings.
  --heading-font-family: "Source Sans Pro", sans-serif;
  --heading-line-height: 1.2;
  --heading-font-weight: bold;

  // The font size for the actual page content is usually larger.
  --paragraph-font-family: "Source Sans Pro", sans-serif;
  --paragraph-font-size: var(--font-size-500); // 18px
  --paragraph-line-height: 1.5;
  --paragraph-margin: 1em;

  // The standard font sizes that are used throughout the site.
  --font-size-100: 2.625rem;  // 42px
  --font-size-200: 2rem;      // 32px
  --font-size-300: 1.625rem;  // 26px
  --font-size-400: 1.25rem;   // 20px
  --font-size-500: 1.125rem;   // 18px
  --font-size-600: 1rem;      // 16px
  --font-size-700: .8rem;     // 12.8px
}

// Set the default document font to the paragraph text.
body {
  font-family: var(--paragraph-font-family);
}

// Common spacing and styles for all headings.
h1, h2, h3, h4, h5, h6 {
  margin: 1em 0 .5em;
  font-family: var(--heading-font-family);
  line-height: var(--heading-line-height);
  font-weight: var(--heading-font-weight);
}

// Sizes of the different heading levels.
h1 { font-size: var(--font-size-100); }
h2 { font-size: var(--font-size-200); }
h3 { font-size: var(--font-size-300); }
h4 { font-size: var(--font-size-400); }
h5 { font-size: var(--font-size-500); }
h6 { font-size: var(--font-size-600); }


// Set the size all paragraphs and long-text content.
p {
  font-size: var(--paragraph-font-size);
  line-height: var(--paragraph-line-height);
  margin: var(--paragraph-margin) 0;
}

Inline Code and Code Blocks

The code tag that is used to format code both within paragraph text and as a block within a figure tag.

Sample

The point of using Lorem Ipsum is that it has a more-or-less normal distribution of letters, as opposed to using echo "Content here, content here", making it look like readable English.

<p>The point of using Lorem Ipsum is that it has a more-or-less normal distribution of letters, as opposed to using <code>Content here, content here</code>, making it look like readable English. </p>
A block of code or markup.
Sample Twig 
<p>The point of using Lorem Ipsum is that it has a more-or-less normal distribution of letters, as opposed to using <code class="language-bash">echo "Content here, content here"</code>, making it look like readable English.</p>

<figure>
  <code class="language-html">
&lt;p&gt;The point of using Lorem Ipsum is that it has a more-or-less normal
  distribution of letters, as opposed to using &lt;code&gt;Content here, content
  here&lt;/code&gt;, making it look like readable English.
&lt;/p&gt;
  </code>
  <figcaption>A block of code or markup.</figcaption>
</figure>
SCSS 
code {
  background: var(--color-white) !important;
  border: .07em solid var(--color-grey-80);
  font-family: monospace;
  padding: .1em .3em;
  font-size: .9em !important;

  // If the code is wrapped in a figure tag, then it should be formatted as a block of text.
  figure > &, pre > & {
    display: block;
    padding: 1em !important;
    white-space: pre-wrap !important;
    line-height: var(--paragraph-line-height);

    // If a caption is included after the code block give it the same background color as the border.
    + figcaption {
      display: inline-block;
      background: var(--color-grey-80);
    }
  }
}

Figure

A figure tag which can contain things like images and blocks of code.

Sample
The Kalastatic site logo.
Sample Twig 
<figure>
  <img src="{{ base_url }}/assets/logo.svg" width="300" height="300" />
  <figcaption>The Kalastatic site logo.</figcaption>
</figure>
SCSS 
// By default, give figures the same font size and margin as a paragraph.
figure {
  font-size: var(--paragraph-font-size);
  line-height: var(--paragraph-line-height);
  margin: 2em 0;

  // The caption text that describes the figure.
  figcaption {
    font-size: .9em;
    font-style: italic;
    padding: .5em 1em;

    // If someone wraps the figcaption text in paragraphs, ensure there isn't too much space at the top and bottom.
    > *:first-child {
      margin-top: 0;
    }
    > *:last-child {
      margin-bottom: 0;
    }
  }


}

Menu

A generic menu, with an unordered list of links wrapped in a nav element.

Sample
Sample Twig 
{% embed "@components/menus/menu.html.twig" only %}

  {# Set the title for this menu (even though it will be visually hidden). #}
  {% set menu_title = "Sample Menu" %}

  {# Create some generic links that don't go anywhere. #}
  {% set menu_items = [
      { 'href': "#", 'title': "Menu Link 1" },
      { 'href': "#", 'title': "Menu Link 2" },
      { 'href': "#", 'title': "Menu Link 3" },
      { 'href': "#", 'title': "Menu Link 4" },
      { 'href': "#", 'title': "Menu Link 5" },
      { 'href': "#", 'title': "Menu Link 6" },
    ]
  %}
{% endembed %}
Twig Template 
{# Set the class for this component, including any classes set by variants. #}
{% set classes = [
    'menu'
  ]|merge(classes ?? [])
%}

<nav class="{{ classes|join(" ") }}">
  <h2>{{ menu_title }}</h2>
  <ul>
    {% for item in menu_items %}
      <li><a href="{{ base_url }}{{ item.href }}">{{ item.title }}</a></li>
    {% endfor %}
  </ul>
</nav>

Menu: Main Menu

The main menu for the site which is dynamically created by iterating through all of the twig files in the pages namespace.

Sample
Sample Twig 
{# Just let it do its magic by looking through the pages namespace. #}
{% embed "@components/menus/menu--main.html.twig" only %}
{% endembed %}
Twig Template 
{% extends "menu.html.twig" %}

{# Set the class for this component. #}
{% set classes = ['menu--main'] %}

{# Set the title for this menu (even though it will be visually hidden). #}
{% set menu_title = "Main menu" %}

{# Get the url for each section, which is the directory without the pages namespace and index.html.twig. #}
{% set sections = [] %}
{% for filename in get_namespace_files('pages') %}
  {% if 'index.html.twig' in filename %}
    {% set sections = [filename|replace({'@pages': '', 'index.html.twig': ''})]|merge(sections) %}
  {% endif %}
{% endfor %}

{# Iterate through all of the component files and output the pages as menu items. #}
{% set menu_items = [] %}
{% for section in sections|sort %}
    {% import '@pages' ~ section ~ 'index.html.twig' as page %}
    {% if page.menu_title is defined %}
      {% set menu_items = menu_items|merge([{ 'href': section, 'title': page.menu_title() }]) %}
    {% endif %}
{% endfor %}

Section

A general section pattern with a section tag, h2 heading, and content.

Sample

What is lorem ipsum?

Content here

Sample Twig 
{% embed "section--text.html.twig" only %}
  {% set heading = "What is lorem ipsum?" %}
  {% block content %}
    <p>Content here</p>
  {% endblock content %}
{% endembed %}
Twig Template 
{# Set the class for this component, including any classes set by variants. #}
{% set classes = [
    'section'
  ]|merge(classes ?? [])
%}

<section id="{{ heading|clean_id }}" class="{{ classes|join(" ") }}">
  <h2>{{ heading }}</h2>
  {% block content %}
  {% endblock content %}
</section>
SCSS 
.section {
  padding: 0 var(--container-padding) var(--container-padding);
  border-bottom: .2rem solid var(--color-white);

}

Section: Text

A section whose content is primarly a block of text, possibly with images or media embedded within.

Sample

What is lorem ipsum?

Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.

Sample Twig 
{% embed "section--text.html.twig" only %}
  {% set heading = "What is lorem ipsum?" %}
  {% block text %}
    <p>
      Lorem Ipsum is simply dummy text of the printing and typesetting
      industry. Lorem Ipsum has been the industry's standard dummy text ever
      since the 1500s, when an unknown printer took a galley of type and
      scrambled it to make a type specimen book. It has survived not only five
      centuries, but also the leap into electronic typesetting, remaining
      essentially unchanged. It was popularised in the 1960s with the release
      of Letraset sheets containing Lorem Ipsum passages, and more recently
      with desktop publishing software like Aldus PageMaker including versions
      of Lorem Ipsum.
    </p>
  {% endblock text %}
{% endembed %}
Twig Template 
{% extends "@components/sections/section.html.twig" %}

{# Set the class for this component. #}
{% set classes = [
    'section--text'
  ]
%}

{# Allow a block of text to be placed in the content. #}
{% block content %}
  {% block text %}
  {% endblock text %}
{% endblock content %}
SCSS 
.section--text {
  > * {
    max-width: 60rem;
  }
}

Template Region: Header

The header region at the top of the page template that includes the logo.

Sample
Kalastatic
Sample Twig 
{% embed "template-region--header.html.twig" only %}
{% endembed %}
Twig Template 
<header class="template-region--header">
  <div class="template-region--header__logo">
    <a href="{{ base_url }}/"><img src="{{ base_url }}/assets/logo.svg" aria-label="Lorem Ipsum"/></a>
  </div>

  {# The site name and menu, which are shown side-by-side when there is room. #}
  <div class="template-region--header__text">
    <div class="template-region--header__site-title"><a href="{{ base_url }}/">Kalastatic</a></div>

    {% embed "@components/menus/menu--main.html.twig" %}{% endembed %}
</header>
SCSS 
.template-region--header {
  padding: var(--container-padding);
  &, a {
    color: var(--color-grey-10);
    text-decoration: none;
  }

  &, &__text {
    display: flex;
    flex-wrap: wrap;
    gap: var(--gap-width);
    align-items: center;
  }

  &__logo {
    img {
      width: 6rem;
      height: 6rem;
    }
  }

  &__text {
    justify-content: space-between;
    flex-grow: 1;
  }

  &__site-title {
    font-size: var(--font-size-100);
  }

  .menu--main {
    h2 {
      display: none; // Need to get visually-hidden mixin.
    }
    ul {
      margin: 0;
      padding: 0;
      display: flex;
      flex-wrap: wrap;
      font-size: var(--font-size-400);
      gap: 1em;
      list-style: none;
      li {
        margin: 0;
        padding: 0;
        a:hover {
          text-decoration: underline;
        }
      }
    }
  }
}