docs/customizing.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <meta http-equiv="X-UA-Compatible" content="ie=edge">
  <meta name="description" content="Learn how to customize Shoelace.css with CSS variables.">
  <link rel="icon" href="../source/img/favicon.png">
  <link rel="stylesheet" href="../dist/shoelace.css">
  <link rel="stylesheet" href="../source/css/_docs.css">
  <link rel="stylesheet" href="https://cdn.rawgit.com/AGMStudio/prism-theme-one-dark/f81fe477/prism-onedark.css">
  <title>Customizing</title>
</head>
<body>

  <header id="head" class="text-center">
    <h1>
      <a href="../index.html">
        <img src="../source/img/wordmark.svg" alt="Shoelace logo">
      </a>
    </h1>

    <p class="text-secondary text-small">
      A back to the basics CSS starter kit. For when you don’t need the whole boot.
    </p>
  </header>

  <main class="container">
    <div class="row">
      <div class="col-md-3">
        <ul id="nav">
          <li><a href="installing.html">Installing</a></li>
          <li><a href="customizing.html">Customizing</a></li>
          <li><a href="content.html">Content</a></li>
          <li><a href="alerts.html">Alerts</a></li>
          <li><a href="badges.html">Badges</a></li>
          <li><a href="buttons.html">Buttons</a></li>
          <li><a href="dropdowns.html">Dropdowns</a></li>
          <li><a href="file-buttons.html">File Buttons</a></li>
          <li><a href="forms.html">Forms</a></li>
          <li><a href="grid-system.html">Grid System</a></li>
          <li><a href="loaders.html">Loaders</a></li>
          <li><a href="progress-bars.html">Progress Bars</a></li>
          <li><a href="switches.html">Switches</a></li>
          <li><a href="tabs.html">Tabs</a></li>
          <li><a href="tables.html">Tables</a></li>
          <li><a href="utilities.html">Utilities</a></li>
          <li><a href="icons.html">Icons</a></li>
          <li><a href="browser-support.html">Browser Support</a></li>
          <li><a href="attribution.html">Attribution</a></li>
        </ul>
      </div>

      <div class="col-md-9">
        <div id="content">
          <h2 id="customizing">Customizing</h2>
<p>If you’re using the source version of Shoelace (i.e. not the CDN or <code>/dist</code> version), you can customize components using CSS variables. To add customizations, simply override one or more of the variables found in <a href="../source/css/variables.css"><code>source/css/variables.css</code></a>.</p>
<p>For example, you can customize the default text color, background color, and the primary color by adding this to your stylesheet:</p>
<pre><code class="lang-css">:root {
  --body-color: white;
  --body-bg-color: black;
  --state-primary: tomato;
}
</code></pre>
<p>You don’t need to include all of the core variables. You only need to include the ones you want to customize.</p>
<h3 id="using-css-variables">Using CSS Variables</h3>
<p>You’re encouraged to use Shoelace’s variables in your own stylesheet. This makes it easy to reuse values without hardcoding them. It also provides a foundation for extending Shoelace with your own <a href="#creating-custom-components">custom components</a>.</p>
<pre><code class="lang-css">.your-component {
  background-color: var(--component-bg-color);
  border-color: var(--component-border-color);
  color: var(--state-secondary);
}
</code></pre>
<p>If you’re not familiar with CSS variables, <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_variables">this article</a> will bring you up to speed.</p>
<h3 id="creating-custom-components">Creating Custom Components</h3>
<p>You can create custom components to extend Shoelace’s functionality. Here’s what a component stylesheet looks like.</p>
<pre><code class="lang-css">/* Set default variables in a :root block. It&#39;s a good idea to
   base them off core variables when possible. This makes it
   easier to customize the library as a whole but still lets
   users change individual components.

   Never change or override core variables!
*/
:root {
  --accordion-bg-color: var(--component-bg-color);
  --accordion-border-color: var(--component-border-color);
  /* etc. */
}

/* Component styles */
.accordion {
  /* Base styles go here. */

  /* Modifiers can be nested and should always be prefixed with
     the component&#39;s name.
  */
  &amp;.accordion-xs { }
  &amp;.accordion-sm { }
  &amp;.accordion-lg { }
  &amp;.accordion-xl { }
}
</code></pre>
<p>Here are some best practices for creating custom components:</p>
<p><strong>Familiarize yourself with Shoelace’s naming conventions.</strong> A custom accordion component, for example, would have a class name such as <code>accordion</code>, modifier classes such as <code>accordion-xs</code>, and variable names that look like <code>--accordion-bg-color</code>. Try to follow the same patterns as much as possible.</p>
<p><strong>Define new variables when it makes sense to.</strong> Take a look at how existing components are defined. Many use core variables instead of hardcoded properties as default values. This makes it easy for users to customize things quickly, but still provides enough flexibility to style individual components.</p>
<p><strong>Provide source and dist versions.</strong> Many people use Shoelace as a tool for prototyping. If you’re open sourcing your component, it’s best to provide both source and dist versions. The dist version is just a minified version of the source after it’s been processed by cssnext.</p>
<p><strong>Semantic markup is strongly encouraged.</strong> Custom components should use the most appropriate elements and the minimal amount of markup required.</p>

        </div>
      </div>
  </main>

  <footer id="foot">
    <a href="../index.html">
      <img src="../source/img/wordmark.svg" alt="Shoelace logo">
    </a>

    <p class="text-small text-secondary">
      1.0.0-beta22
    </p>

    <p class="mar-y-sm text-center">
      <a class="github-button" href="https://github.com/claviska/shoelace-css/fork" data-size="large" aria-label="Fork claviska/shoelace-css on GitHub">Fork</a>
      <a class="github-button" href="https://github.com/claviska/shoelace-css/releases" data-icon="octicon-cloud-download" data-size="large" aria-label="Download claviska/shoelace-css on GitHub">Download</a>
      <a class="github-button" href="https://github.com/claviska/shoelace-css/issues" data-icon="octicon-issue-opened" data-size="large" aria-label="Issue claviska/shoelace-css on GitHub">Report a Bug</a>
      <a class="github-button" href="https://github.com/claviska/shoelace-css" data-icon="octicon-star" data-size="large" data-show-count="true" aria-label="Star claviska/shoelace-css on GitHub">Star</a>
    </p>

    <p>
      <a href="https://twitter.com/shoelacecss" class="button button-info" style="margin-bottom: 1.2rem;">Follow</a>
      <a href="https://paypal.me/claviska" class="button button-success" style="margin-bottom: 1.2rem;">Donate</a>
    </p>

    <p class="text-small text-secondary">
      <a href="https://keycdn.com/" class="text-secondary">Accelerated by KeyCDN</a> &middot;
      &copy; A Beautiful Site, LLC
    </p>
  </footer>

  <script src="https://cdnjs.cloudflare.com/ajax/libs/zepto/1.2.0/zepto.min.js"></script>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.6.0/prism.min.js"></script>
  <script src="../dist/shoelace.js"></script>
  <script>
    $(function() {
      // Highlight current nav item
      $('#nav a').each(function() {
        if(this.pathname === location.pathname) {
          $(this).addClass('current');
        }
      });

      // Intercept dropdown clicks for the demo
      $('.dropdown').on('select', function(event) {
        event.preventDefault();
      });
    });
  </script>
  <script async defer src="https://buttons.github.io/buttons.js"></script>
</body>
</html>