@zeix/ui-element

<!doctype html> <html lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Styling – UIElement Docs</title> <meta name="description" content="Scoped styles, CSS custom properties" /> <link rel="stylesheet" href="./assets/main.css" /> <script type="module" src="./assets/main.js"></script> </head> <body class=""> <context-router> <header class="content-grid"> <h1 class="content"> UIElement Docs Version 0.13.3 </h1> <section-menu> <nav> <h2 class="visually-hidden">Main Menu</h2> <ol> <li> <a href="index.html"> 📖 Introduction Overview and key benefits of UIElement </a> </li> <li> <a href="getting-started.html"> 🚀 Getting Started Installation, setup, and first steps </a> </li> <li> <a href="components.html"> 🏗️ Components Anatomy, lifecycle, signals, effects </a> </li> <li> <a href="styling.html"> 🎨 Styling Scoped styles, CSS custom properties </a> </li> <li> <a href="data-flow.html"> 🔄 Data Flow Passing state, events, context </a> </li> <li> <a href="examples.html"> 🍽️ Examples Common use cases and demos </a> </li> <li> <a href="blog.html"> 📜 Blog Latest articles and updates </a> </li> <li> <a href="api.html"> 📚 API Reference Functions, types, and constants </a> </li> <li> <a href="about.html"> 🤝 About License, versioning, getting involved </a> </li> </ol> </nav> </section-menu> <card-callout class="content danger" hidden> </card-callout> </header> <main class="content-grid"><section-hero> <h1 id="styling"> <a name="styling" class="anchor" href="#styling"> 🔗 </a> 🎨 Styling </h1> <div> Keep your components’ styles self-contained while supporting shared design tokens. UIElement offers a refreshingly simple approach to create reactive Web Components that enhance your existing HTML. <module-toc> <nav> <h2>In this Page</h2> <ol> <li><a href="#design-principles">Design Principles</a></li> <li><a href="#scope-styles-to-custom-element">Scope Styles to Custom Element</a></li> <li><a href="#encapsulate-styles-with-shadow-dom">Encapsulate Styles with Shadow DOM</a></li> <li><a href="#shared-design-tokens-with-css-custom-properties">Shared Design Tokens with CSS Custom Properties</a></li> <li><a href="#defined-variants-with-classes">Defined Variants with Classes</a></li> <li><a href="#css-only-components">CSS-only Components</a></li> <li><a href="#next-steps">Next Steps</a></li> </ol> </nav> </module-toc> </div> </section-hero> <section> <h2 id="design-principles"> <a name="design-principles" class="anchor" href="#design-principles"> 🔗 </a> Design Principles </h2> UIElement is focused on state management and reactivity, not styling. However, to ensure consistent, maintainable, and reusable styles, we recommend techniques that scope component styles properly while allowing shared design tokens (e.g., spacing, font sizes, colors, layout grids). <ul> <li>Each component brings along its own specific styles.</li> <li>Component styles should be scoped or encapsulated so they don't leak out.</li> <li>Allow customizations via CSS custom properties or pre-defined classes.</li> </ul> Parent components may apply styles to the wrapper element of known sub-components for layout purposes. But avoid styling inner elements of sub-components directly. This would tightly couple the styles of the outer and inner components. </section> <section> <h2 id="scope-styles-to-custom-element"> <a name="scope-styles-to-custom-element" class="anchor" href="#scope-styles-to-custom-element"> 🔗 </a> Scope Styles to Custom Element </h2> Use the custom element name to scope component styles if you control the page and the components within. This protects against component styles leaking out, while still allowing to use the CSS cascade. No need for Shadow DOM, no duplicate style rules. <module-codeblock language="css" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> css <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code>my-component { & button { /* Button style rules */ } /* More selectors for inner elements */ } </code></pre> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> </module-codeblock> <h3 id="advantages-of-custom-element-names"> <a name="advantages-of-custom-element-names" class="anchor" href="#advantages-of-custom-element-names"> 🔗 </a> Advantages of Custom Element Names </h3> <ul> <li>By definition unique within the document with a descriptive name.</li> <li>Low specificity, making it easy to override when you need to with a single class.</li> </ul> <card-callout class="tip"> When to use Best when you control the page and need styles to cascade naturally. Avoid if you expect style clashes from third-party styles. </card-callout> </section> <section> <h2 id="encapsulate-styles-with-shadow-dom"> <a name="encapsulate-styles-with-shadow-dom" class="anchor" href="#encapsulate-styles-with-shadow-dom"> 🔗 </a> Encapsulate Styles with Shadow DOM </h2> Use Shadow DOM to encapsulate styles if your component is going to be used in a pages where you don't control the styles. This way you make sure page styles don't leak in and component styles don't leak out. <module-codeblock collapsed language="html" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> html <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code><my-component> <template shadowrootmode="open"> <style> button { /* Button style rules */ } /* More selectors for inner elements */ </style>  </template> </my-component> </code></pre> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> <button type="button" class="overlay">Expand</button> </module-codeblock> <card-callout class="tip"> When to use Best when your component is used in environments where you don’t control styles. Avoid if you need global styles to apply inside the component. </card-callout> </section> <section> <h2 id="shared-design-tokens-with-css-custom-properties"> <a name="shared-design-tokens-with-css-custom-properties" class="anchor" href="#shared-design-tokens-with-css-custom-properties"> 🔗 </a> Shared Design Tokens with CSS Custom Properties </h2> Web Components can't inherit global styles inside Shadow DOM, but CSS custom properties allow components to remain flexible and themeable. <h3 id="defining-design-tokens"> <a name="defining-design-tokens" class="anchor" href="#defining-design-tokens"> 🔗 </a> Defining Design Tokens </h3> Set global tokens in a stylesheet: <module-codeblock language="css" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> css <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code>:root { --button-bg: #007bff; --button-text: #fff; --spacing: 1rem; } </code></pre> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> </module-codeblock> <h3 id="using-tokens-in-a-component"> <a name="using-tokens-in-a-component" class="anchor" href="#using-tokens-in-a-component"> 🔗 </a> Using Tokens in a Component </h3> <module-codeblock language="css" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> css <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code>my-component { padding: var(--spacing); & button { background: var(--button-bg); color: var(--button-text); } } </code></pre> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> </module-codeblock> <h3 id="advantages-of-css-custom-properties"> <a name="advantages-of-css-custom-properties" class="anchor" href="#advantages-of-css-custom-properties"> 🔗 </a> Advantages of CSS Custom Properties </h3> <ul> <li>Supports theming – users can override styles globally.</li> <li>Works inside Shadow DOM – unlike normal CSS, custom properties are inherited inside the shadow tree.</li> </ul> </section> <section> <h2 id="defined-variants-with-classes"> <a name="defined-variants-with-classes" class="anchor" href="#defined-variants-with-classes"> 🔗 </a> Defined Variants with Classes </h2> Use classes if your components can appear in a limited set of specific manifestations. For example, buttons could come in certain sizes and have primary, secondary and tertiary variants. <module-codeblock collapsed language="css" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> css <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code>my-button { /* Style rules for default (medium-sized, secondary) buttons */ &.small { /* Style rules for small buttons */ } &.large { /* Style rules for large buttons */ } &.primary { /* Style rules for primary buttons */ } &.tertiary { /* Style rules for tertiary buttons */ } } </code></pre> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> <button type="button" class="overlay">Expand</button> </module-codeblock> </section> <section> <h2 id="css-only-components"> <a name="css-only-components" class="anchor" href="#css-only-components"> 🔗 </a> CSS-only Components </h2> Just because UIElement is a JavaScript library doesn't mean you have to use JavaScript in every component. It's perfectly fine to use custom elements just for styling purposes. Here's the example of the <code><card-callout></code> we're using in this documentation: <module-demo> <div class="preview"> <card-callout>This is an informational message.</card-callout> <card-callout class="tip">Remember to hydrate while coding!</card-callout> <card-callout class="caution">Be careful with this operation.</card-callout> <card-callout class="danger">This action is irreversible!</card-callout> <card-callout class="note">This is just a side note.</card-callout> </div> <details> <summary>Source Code</summary> <module-lazy src="./examples/card-callout.html"> <card-callout> Loading... </card-callout> </module-lazy> </details> </module-demo> </section> <section> <h2 id="next-steps"> <a name="next-steps" class="anchor" href="#next-steps"> 🔗 </a> Next Steps </h2> Now that you know how to style components, explore: <ul> <li><a href="data-flow.html">Data Flow</a> – learn about communication between components.</li> <li><a href="examples.html">Examples</a> – explore common examples.</li> </ul> </section> </main> <footer class="content-grid"> <div class="content"> <h2 class="visually-hidden">Footer</h2> © 2024 – 2025 Zeix AG </div> </footer> </context-router> </body> </html>