selur

# Selur.css: The UI Declaration Engine _Focus on creativity, not workarounds._ ## 💡 Introduction _A new way to handle CSS._ ### What is Selur? Selur is a **pure CSS interface calculator** that establishes an architectural foundation where visual structure, styling logic, and basic dynamic behavior are driven entirely by CSS. Selur operates on a strict **separation of concerns**: * **Selur's Mandate:** Owns **Structural Logic**, **Responsive State**, and **Interaction Sequencing** via CSS as well as the **CSS parts** of Accessibility Compliance. This leaves **HTML classes free for purely** aesthetic styling. * **Developer's Mandate:** CSS instructions to handle aesthetic design (colors, fonts, radius). Non-CSS based logic of the project or application. This approach delivers a code base that is **structurally sound**, **infinitely maintainable**, and **99% self-sufficient**(minimal JS hydration on legacy browsers) in CSS for dynamic UI behavior. ### Why Selur? Selur is designed to restore the initial web contract: Structure (HTML) → Visual (CSS) → Logic (JS). We aim to give back to CSS the responsibility for visual logic that was historically usurped by JavaScript. Selur is dedicated exclusively to **cosmetic orchestration** with a **"WYWIWYG" (What You Write Is What You Get)** approach. This philosophy keeps the system close to native CSS, ensuring the interface is **intuitive**, **predictable**, and **transparent**, thus eliminating the cognitive debt associated with runtime JS styling. #### The Gain: Eliminating Architectural Bottlenecks Restoring the initial web contract make all issues and bottlenecks induced by bad architecture disappear: * **Performance is Paramount:** Selur offloads complex visual computations from the slow **CPU (JavaScript)** to the fast **GPU (CSS Rendering Engine)**. This guarantees **superior animation fluidity** and **significantly better performance** on all devices. * **Decouple Design and Structure:** Selur enables the independent development of component structure and visual design. A Designer defines aesthetics using Selur's variables, while an Integrator builds functional wireframes using pure semantic HTML and Selur's attributes (e.g., `<input type="checkbox" data-widget="toggle" data-type="bento">`). * **No hidden magic:** Selur’s logic is **fully exposed** through CSS variables and attributes. Since all state changes are handled by the CSS engine, the entire process is **100% auditable** via DevTools or a simple `getComputedStyle` call. This clarity makes **programmatic testing and true automation** accessible for the first time. By letting Selur manage technical implementation, developers focus purely on **what to show**. This naturally eliminates core front-end conflicts: **specificity wars**, **semantic pollution**, and **JS-dependency** for simple UI state management. ### Who Is Selur For? Selur’s architectural **purity** and **simplicity** make it accessible and highly valuable across the entire team: * **Beginners & Non-Developers:**: Selur is as simple as plain HTML. **Just state what you want to get it**. A simple button ? `<button>`. The (commonly) ominously complex 3D carousel slideshow ? `<div data-widget="slideshow" data-type="carousel" data-direction="horizontal" data-indexation="all" data-trigger="focus">`. **Ask and Selur will handle the rest**. * **Purists & Engineers:**: Selur is the generic, high-quality, lightweight code they would write themselves—conceived for scalability, maintainability, and performance. * **Architects & Tech Leads:**: Selur offers a **declarative interface** that allows focus on **visual architecture**, freeing from worrying about **technical implementation details** and **specificity issues**. * **CTO & Business Actors:**: Selur provides exceptional **ROI** —**purist-level code quality** with **business-level productivity**. Designed to **never get old** it drastically reduces technical debt—download it once and use it for life. * **Designers & UX Professionals:**: Selur provides the **canvas and brushes**. Designers just have to choose their colors and paint. No need to erase the initial drawing which leaves marks, or to weave the canvas and craft their own brushes. ## 📦 Quick Start _Setup and Core Usage._ ### Installation To use Selur CSS Library in your project, follow these steps: 1. Download the latest version from the official GitLab repository. 2. Include the `selur.min.css` file in your HTML document's `<head>` section: ```html <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/selur@latest/dist/selur-longhand.min.css" /> ``` ### Usage examples The tags and data attributes tell Selur what to do with which element. The most common are: * `data-widget` defines the visual object behavior and structure. It's the main attribute. * `data-type` defines the visual object form and appearance "details". It's the secondary attribute. * `data-direction` defines the visual object direction. It is optional but required for some visual objects. * `data-indexation` tell Selur how to detect the visual object length and index its children. It is optional but required for some effect objects. * `data-trigger` defines what will affect the visual object state. It is optional but required for some effect objects. **So concretly, what can we do with Selur? Just what you can think of :** * Button and Card : Those are native HTML5 components no need for data attributes Selur enhanced them out of the box.. ```html  <button>Click me</button>  <figure> <picture> <source media="(min-width: 1024px)" srcset="path/to/image.jpg"> <source media="(min-width: 768px)" srcset="path/to/image.jpg"> <source media="(min-width: 480px)" srcset="path/to/image.jpg"> <img src="path/to/image.jpg" alt="Image"> </picture> <figcaption>Image caption</figcaption> </figure> ``` * Tab and Carousel : Those are full-featured components. ```html  <div data-widget="slideshow" data-type="tab" data-indexation="all" data-trigger="target" >  <section id="page-1">  <h2>Page 1</h2> <p>Content of page 1</p> </section> <section id="page-2">  <h2>Page 2</h2> <p>Content of page 2</p> </section> </div>   <div data-widget="slideshow" data-type="carousel" data-indexation="all" data-trigger="focus" data-direction="horizontal" >  <section tabindex="0">  <img src="path/to/image1.jpg" alt="Carousel first slide"> </section> <section tabindex="0">  <img src="path/to/image2.jpg" alt="Carousel second slide"> </section> <section tabindex="0">  <img src="path/to/image3.jpg" alt="Carousel third slide"> </section> <section tabindex="0">  <img src="path/to/image4.jpg" alt="Carousel fourth slide"> </section> <section tabindex="0">  <img src="path/to/image5.jpg" alt="Carousel fifth slide"> </section> <section tabindex="0">  <img src="path/to/image6.jpg" alt="Carousel sixth slide"> </section> </div> ``` * Button group: That's just a cluster of buttons merged into a seemingly single one. ```html  <div data-widget="collage" data-type="group" data-direction="vertical">  <button>Click</button>  <button>One</button> <button>Of</button> <button>Us</button> </div>   ``` * Using JSX: Nothing changes, just delegate the state management to the your framework while letting Selur handle the presentation. ```jsx // A real JSX component using Selur will more be like follow: return ( <> <div data-widget="slideshow" data-type="carousel" data-direction={acceptedDirection.includes(direction) ? direction : "horizontal"} // Still indexes the children on old browser data-indexation="all" // JS style injection replaces data-trigger logic removing the need for an input to create interactivity style={{ "--l--": slides.length, // Set length that CSS can't set on old browser "--state--": currentState, // define the state of the slideshow, Selur handles the presentation. }} > ...slides </div> </> ); // There no data-trigger because the state is defined by the JS framework, not Selur. ``` Just describe what's on the mockups and let Selur do the rest. All the above examples are standalone, you can use them as is. ### 🧱 Available Visual Objects Selur offers a range of visual objects for your projects. Here is a list of currently available objects. Items not yet checked are planned for future development. **HTML Objects** * [x] button: Style the basic, hover/focus, and active states of the `<button>` element. * [x] card: Style the `<figure>` element (includes `<figcaption>`). * [ ] field: Style the `<input>`, `<textarea>`, and `<select>` elements. * [ ] fold: Style the `<details>` element. * [ ] form: Style the `<form>` element. * [ ] gauge: Style the `<meter>` and `<progress>` elements. * [ ] heading: Style the `<h1>` to `<h6>` elements. * [ ] link: Style the `<a>` element. * [ ] list: Style the `<ul>` and `<ol>` elements. * [ ] modal: Style the `<dialog>` element. * [ ] table: Style the `<table>` element. **Custom Objects** * [ ] info: Informational visual object. * [ ] badge: Small element for displaying short information like counts, status, or categories. * [ ] notification: Alert message display for conveying important information to users. * [ ] landmark: Point of interest and callout. * [ ] banner: Large display for showcasing important information or promotions. * [ ] ribbon: Decorative element for highlighting important sections or features. * [ ] navControl: Navigation control. * [ ] breadcrumb: Navigation aid for indicating the current page's position in a hierarchy. * [ ] indicator: Visual cues for navigation. * [ ] pagination: Enumerated page links container. * [ ] tab: Tab links container. * [ ] tag: Small, clickable label for categorizing or tagging content. * [x] toggle: Two states visual object. * [x] bento: Nine-dots in a square menu icon. Shows a dot with four lines forming a five-part cross when active. * [x] button: Two-state push button. * [x] fried: Three-line menu icon with a narrower middle line. * [x] hamburger: Three-line menu icon. Forms a cross when active. * [x] hotdog: Centered three-line menu icon with a wider middle line. Forms a cross when active. * [x] kebab: Vertical three-dots menu icon. Shows a dot with four lines forming a five-part cross when active. * [x] meatball: Horizontal three-dots menu icon. Shows a dot with four lines forming a five-part cross when active. * [x] switch: Styled for on/off toggle control. * [ ] track: Sequential items. * [ ] events: Vertical or horizontal representation of sequential items like timelines, history, steps, etc. **Effect Objects** * [x] animate: Apply animation to all direct children. * [x] state: Run animation on state change. * [ ] view: Run animation on view change. * [ ] scroll: Run animation on scroll change. * [x] appearance: Define the design of all descendant visual objects. * [x] Legacy: Modern, browser-like standard appearance with subtle enhancements. * [ ] glassmorphic: Creates a frosted glass effect with semi-transparent backgrounds and subtle blur, providing depth and elegance. * [ ] elevated: Applies a 3D raised effect using shadows and highlights to create a sense of depth and prominence. * [x] flat: Implements a clean, two-dimensional design without shadows or depth effects, focusing on color and typography. * [ ] grunge: Adds a distressed, textured look with rough edges, worn appearance, and organic imperfections for a raw aesthetic. * [ ] neumorphism: Creates a soft 3D embossed effect using subtle shadows and highlights, giving a tactile, almost physical feel to UI elements. * [ ] minimal: Focuses on simplicity with clean lines and uncluttered design. * [ ] vintage: Emulates the classic look of early web design, reminiscent of the HTML 1.0 era. * [x] collage: Place its direct children in a layout. * [x] group: Align horizontally or vertically direct children and reallocate "edge properties" like border-radius in its children. (can be used to create a button group by example) * [x] masonry: Create a vertical or horizontal masonry layout. * [ ] stacked: Group elements into a seemingly single element and dynamically stack/unstack them based on a trigger. * [x] structured: Create a grid with repeating patterns. * [ ] unstructured: Column and row free dense layout. * [x] menu: Navigation menu. * [ ] drawer: Hide its content and show it on trigger (usually on click). * [x] dropdown: Hide second child (usually a link container) and show it on trigger (usually on hover). * [x] navbar: Place content horizontally and hide the direct children that have the ??? attribute. On breakpoint, hide the nav element and show the one that has the ??? attribute. When triggered, show the nav element like the dropdown second child. * [x] slideshow: Show one or more child at a time.  * [x] carousel: Place its direct children in a 3D circular layout and rotate on the X or Y axis to show the active child. * [x] slider: Place its direct children in a linear layout and slide on the X or Y axis to show the active child. * [x] tab: Superpose its direct children and hide all but the active one. * [ ] wheel: Place its direct children in a circular layout and rotate on the Z axis to show the active child. **core**: There are two additional visual objects (custom and effect) that are empty containers for user made custom and effect objects (e.g. `[data-widget="custom|effect"][data-type="my-personal-widget"]`). ## ❓ FAQ **How is Selur different from other frameworks?** Selur solves a different problem. Its core focus is on **architectural integrity** and providing a conflict-free foundation. It is solely based on semantic and provides the **structural plumbing**, not the paint (We guarantee only modifications made through Selur variables). Selur make the house stable and durable, you make it memorable. **What about browser support? Is it safe for production?** Selur is built to reduce cosmetic complexity and JS workload related to it back to IE11(If CSS variables are supported, Selur too.). It do it by exposing 2 CSS variables (`--l--` and `--state--`), that once filled or updated, allow Selur to handle advanced interactivity. Additionnaly, on browser that support it, `:has()` pseudo-class is used to fill them enabling pure CSS interactivity . **Do I have to stop using JavaScript to use Selur?** **No**. Selur is "JavaScript-free" **not** "JavaScript-hostile". The philosophy is to use the right tool for the job. Selur handle what CSS meant to do: **presentation**. Allowing HTML to do the same by focusing on **semantic structure**, and so on for JavaScript on handling **application-level logic**. **Are Selur's components fully accessible out-of-the-box?** Selur is built with a strong accessibility foundation: it enhances native semantic HTML, offers an ARIA-based syntax, and includes an automatic WCAG contrast system. However, it's crucial to understand its scope: Selur manages the **visual design and structure**. Complex accessibility patterns and dynamic attributes updates are the **developer's responsibility**. Selur only gives an accessible starting point. **Is Selur difficult to learn?** Selur is designed to be intuitive and have a much smaller learning curve than large, all-encompassing frameworks. You only need to learn its **declarative API (the HTML attributes)**, each Visual Object is **atomic and self-contained**, which allows for **progressive learning**. **Selur handles the complexity and ensures no visual regression** thanks to its focused scope, making integration significantly faster than learning the entire surface area of a utility framework. **Selur is presented a kind interface-making miracle, can you keed this promise?** Selur wasn't designed to solve all the world's problems, but merely to simplify the use of CSS without complicating HTML or JS. We aimed for the lightest and most seamless possible integration. All mindblowing magical features are, in fact, side effects of a clean, robust architecture, rather than consciously designed utilities. Selur's true promise is architectural integrity. ## 🛡️ Disclaimer and Compatibility * **Selur's Mandate and Nature:** Selur is a **CSS framework** and **only handles CSS**. It never intended to do anything do anything else than to provide a robust, maintainable, and scalable CSS simplification. * **Selur's UI State Management:** The UI state management provided by `[data-trigger]` and the length detection of `[data-indexation]` are based on the `:has()` selector. Thus `[data-trigger]` has no effect on older browsers and `[data-indexation]` can only offers half of its functionality (Still indexes the children). All the other features are based basic CSS properties and selectors. For projects requiring broader support, refer to the FAQ for the **[graceful degradation](path/to/wikis/graceful-degradation.md)** alternatives. * **Design and Aesthetic Neutrality:** Selur is aesthetically neutral but not ugly or poorly designed. It provides a raw, unopinionated, design which reproduces a slightly augmented version of the default appearance of web browsers. * **Selur’s 100% JS-free character:** Selur simplify UI development. It does **NOT** frees you of JavaScript but **doesn't require it**. All functionality that belongs to JavaScript (e.g., application logic, complex state management) still requires JavaScript. Selur only handles **CSS** because it's a **CSS framework** and all its utilities are **PURE CSS**. ## 📜 License Selur CSS Library is licensed under the MIT License. See the [LICENSE](./LICENSE) file for more information. ## 💬 Support and Community * Documentation: [Link to documentation](https://gitlab.com/tdj.dev/selur/-/wikis/home) * GitLab Issues: [Link to GitLab issues](https://gitlab.com/tdj.dev/selur/-/issues) ## 🔖 Changelog For a detailed changelog, please [see the CHANGELOG.md](./CHANGELOG.md) file in the repository. ## ✅ Conclusion Selur redefines CSS styling with its unique approach, combining the flexibility of a library with the scalability of a framework. Selur provides the tools and freedom you need for high-quality, maintainable designs. *** Selur makes UI styling clean and reliable. We hope you find it useful. Happy coding!