js/shoelace
1
0
Fork 0
mirror of https://github.com/shoelace-style/shoelace.git synced 2026-01-12 11:09:13 +00:00
Code Issues Packages Projects Releases Wiki Activity

Updating customizing docs

Browse Source
This commit is contained in:
Cory LaViska
2017-08-18 14:08:16 -04:00
parent 7a1897c534
commit 75614a2fdb
2 changed files with 41 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
docs/customizing.html
View File

@@ -48,29 +48,29 @@
<div id="content">
<h2 id="customizing">Customizing</h2>
<p>You can customize Shoelace without editing core files or using a preprocessor. To add customizations, simply override one or more of the variables found in the <code>:root</code> block of <a href="../source/css/shoelace.css"><code>shoelace.css</code></a>.</p>
<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 the <code>:root</code> block of <a href="../source/css/shoelace.css"><code>shoelace.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: #09d;
--state-primary: tomato;
}
</code></pre>
<p>You don’t need to include all of the variables. You only need to override the ones you actually want to customize.</p>
<p>Additional variables can be found in the <code>:root</code> block of each component’s stylesheet. For example, to customize alerts, refer to the top of <a href="https://github.com/claviska/shoelace-css/blob/master/source/css/alerts.css"><code>alerts.css</code></a> for a list of variables.</p>
<p>You don’t need to include all of the core variables. You only need to include the ones you want to customize.</p>
<p>Additional variables can be found in the <code>:root</code> block of each component’s stylesheet. For example, to customize alerts, refer to the top of <a href="https://github.com/claviska/shoelace-css/blob/master/source/css/alerts.css"><code>alerts.css</code></a> for a complete list of variables.</p>
<h3 id="using-variables">Using Variables</h3>
<p>You can use any of 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-selector {
color: var(--state-danger);
}
</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. There’s also an <a href="https://codepen.io/claviska/pen/NvGVYM?editors=1100">interactive demo</a> if you want to experiment.</p>
<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’s stylesheet looks like.</p>
<pre><code class="lang-css">/* Set default variables here. 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.
<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 in your extension!
*/
@@ -80,21 +80,24 @@
/* etc. */
}
/* Add your styles here. Create additional rules as needed. */
/* Component styles */
.accordion {
/* Base styles go here. */
}
/* Always prefix your modifiers with the component name. */
.accordion-modifier {
/* 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-open</code>, and variable names that look like <code>--accordion-bg-color</code>. Try to follow similar patterns as much as possible.</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>
<p><strong>Keep things together.</strong> Each component should be in its own folder along with its stylesheets, scripts, and documentation. Components can use core variables, but they shouldn’t depend on other components’ styles or scripts to work. This makes it easier to add or remove components from your app without worrying about dependencies.</p>
</div>
</main>

39
source/docs/customizing.md
View File

@@ -6,7 +6,7 @@ description: Learn how to customize Shoelace.css with CSS variables.
## Customizing
You can customize Shoelace without editing core files or using a preprocessor. To add customizations, simply override one or more of the variables found in the `:root` block of [`shoelace.css`](../source/css/shoelace.css).
If you’re using the source version of Shoelace (i.e. not the CDN or `/dist` version), you can customize components using CSS variables. To add customizations, simply override one or more of the variables found in the `:root` block of [`shoelace.css`](../source/css/shoelace.css).
For example, you can customize the default text color, background color, and the primary color by adding this to your stylesheet:
@@ -14,13 +14,13 @@ For example, you can customize the default text color, background color, and the
:root {
--body-color: white;
--body-bg-color: black;
--state-primary: #09d;
--state-primary: tomato;
}
```
You don’t need to include all of the variables. You only need to override the ones you actually want to customize.
You don’t need to include all of the core variables. You only need to include the ones you want to customize.
Additional variables can be found in the `:root` block of each component’s stylesheet. For example, to customize alerts, refer to the top of [`alerts.css`](https://github.com/claviska/shoelace-css/blob/master/source/css/alerts.css) for a list of variables.
Additional variables can be found in the `:root` block of each component’s stylesheet. For example, to customize alerts, refer to the top of [`alerts.css`](https://github.com/claviska/shoelace-css/blob/master/source/css/alerts.css) for a complete list of variables.
### Using Variables
@@ -32,17 +32,17 @@ You can use any of Shoelace’s variables in your own stylesheet. This makes it
}
```
If you’re not familiar with CSS variables, [this article](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_variables) will bring you up to speed. There’s also an [interactive demo](https://codepen.io/claviska/pen/NvGVYM?editors=1100) if you want to experiment.
If you’re not familiar with CSS variables, [this article](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_variables) will bring you up to speed.
### Creating Custom Components
You can create custom components to extend Shoelace’s functionality. Here’s what a component’s stylesheet looks like.
```css
/* Set default variables here. It'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.
/* Set default variables in a :root block. It'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 in your extension!
*/
@@ -52,23 +52,26 @@ You can create custom components to extend Shoelace’s functionality. Here’s
/* etc. */
}
/* Add your styles here. Create additional rules as needed. */
/* Component styles */
.accordion {
/* Base styles go here. */
}
/* Always prefix your modifiers with the component name. */
.accordion-modifier {
/* Modifiers can be nested and should always be prefixed with
the component's name.
*/
&.accordion-xs { }
&.accordion-sm { }
&.accordion-lg { }
&.accordion-xl { }
}
```
Here are some best practices for creating custom components:
**Familiarize yourself with Shoelace’s naming conventions.** A custom accordion component, for example, would have a class name such as `accordion`, modifier classes such as `accordion-open`, and variable names that look like `--accordion-bg-color`. Try to follow similar patterns as much as possible.
**Familiarize yourself with Shoelace’s naming conventions.** A custom accordion component, for example, would have a class name such as `accordion`, modifier classes such as `accordion-xs`, and variable names that look like `--accordion-bg-color`. Try to follow the same patterns as much as possible.
**Define new variables when it makes sense to.** 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.
**Semantic markup is strongly encouraged.** Custom components should use the most appropriate elements and the minimal amount of markup required.
**Provide source and dist versions.** 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.
**Keep things together.** Each component should be in its own folder along with its stylesheets, scripts, and documentation. Components can use core variables, but they shouldn’t depend on other components’ styles or scripts to work. This makes it easier to add or remove components from your app without worrying about dependencies.
**Semantic markup is strongly encouraged.** Custom components should use the most appropriate elements and the minimal amount of markup required.