@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 Components – 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> <header class="content-grid"> <h1 class="content">UIElement Docs Version 0.11.0</h1> <nav class="breakout"> <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="building-components.html"> 🏗️ Building Components Anatomy, lifecycle, signals, effects </a> </li> <li> <a href="styling-components.html" class="active"> 🎨 Styling Components Scoped styles, CSS custom properties </a> </li> <li> <a href="data-flow.html"> 🔄 Data Flow Passing state, events, context </a> </li> <li> <a href="patterns-techniques.html"> 💡 Patterns & Techniques Composition, scheduling, best practices </a> </li> <li> <a href="examples-recipes.html"> 🍽️ Examples & Recipes Common use cases and demos </a> </li> <li> <a href="api-reference.html"> 📚 API Reference Detailed documentation of classes and functions </a> </li> <li> <a href="about-community.html"> 🤝 About & Community License, versioning, getting involved </a> </li> </ol> </nav> </header> <main> <section class="hero"> <h1>🎨 Styling Components</h1> Keep your components’ styles self-contained while supporting shared design tokens. UIElement does not enforce a specific styling method, but we recommend techniques that help balance encapsulation, reusability, and maintainability. </section> <section> <h2>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>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. <code-block 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> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> </code-block> <h3>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> <callout-box 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. </callout-box> </section> <section> <h2>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. <code-block 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> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> <button type="button" class="overlay">Expand</button> </code-block> <callout-box 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. </callout-box> </section> <section> <h2>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>Defining Design Tokens</h3> Set global tokens in a stylesheet: <code-block 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> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> </code-block> <h3>Using Tokens in a Component</h3> <code-block 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> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> </code-block> <h3>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>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. <code-block 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> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> <button type="button" class="overlay">Expand</button> </code-block> </section> <section> <h2>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><callout-box></code> we're using in this documentation: <component-demo> <div class="preview"> <callout-box>This is an informational message.</callout-box> <callout-box class="tip">Remember to hydrate while coding!</callout-box> <callout-box class="caution">Be careful with this operation.</callout-box> <callout-box class="danger">This action is irreversible!</callout-box> <callout-box class="note">This is just a side note.</callout-box> </div> <details> <summary>Source Code</summary> <lazy-load src="./examples/callout-box.html"> Loading... </lazy-load> </details> </component-demo> </section> <section> <h2>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="patterns-techniques.html">Patterns & Techniques</a> – Explore best practices and advanced topics.</li> </ul> </section> </main> <footer class="content-grid"> <div class="content"> <h2 class="visually-hidden">Footer</h2> © 2025 Zeix AG </div> </footer> </body> </html>