When we started DomUI we did our best to have some rules for components. But of course we learned a lot, and in the best way possible: by making mistakes. The sad news, of course, is that those mistakes live on in the framework. This is why we have multiple versions of components, like LookupInput and LookupInput2. The higher the number the better the control is supposed to be (and incidentally the more stubbornly wrong we were).
If a component has no numbered version this does not necessarily mean it's perfect, though 
Related to the quality of the components is the quality of the style sheets and style sheet rules associated with the components. DomUI has a highly flexible theming engine which allows for many ways of organizing style sheets. DomUI's styling also preceded the current flock of CSS preprocessors like Sass and Less, so it implements some logic by itself in the older stylesheets. Because DomUI was primarily used by a corporation with special UI needs there are multiple style sheets, most of them of questionable overall quality.
Starting with DomUI 2.0 all new components will get their styles from the SCSS stylesheet provider. These stylesheets use standard SCSS, and obey stricter rules around how components and pages should be styled. The existing "legacy" stylesheets should continue to work just fine, and we're taking care to not change the components in such a way that they are impossible to use with the older stylesheets. But new components and layout fixes will mostly be done in the new SCSS theme, "winter".
Stylesheet rules
Reset scripts - no longer used
The earlier DomUI stylesheets used a "CSS reset script" to clear the default styling off all HTML tags. The idea was that after this the behavior of the tags would be more easily controlled, and that this behavior would be the same for all browsers.
But using a reset sheet has quite a few side effects... Most of these are not too bad for websites and not too big applications, but for bigger stuff they get in the way:
- The reset script is not that easy to do well. So its effects percolate through to your own styles, often in unexpected results.
- Lots of functions actually want to show HTML. And those functions expect that html to be rendered in a reasonable way. Removing all formatting means that this does not hold, at all: by default it looks like flat text. The solution means adding back all those styles carefully removed by the reset script, sigh. Which means you STILL have to consider the "native" styles of tags.
Consequently the newer DomUI stylesheets do away with reset scripts completely.
The effects of this are not too bad: using the per-component classes (see below) you can more easily address styling of html tags used in the components and reset them only where needed. In addition DomUI mostly uses the styleless div and span tags, and just adds styling by giving those a class where needed.
One fragment per component
Each component must have its own stylesheet fragment which contains most of the scss needed to render the component. For a component like LookupInput2 there is a fragment called _lookupinput2.scss. These fragments are included in the master stylesheet called theme.style.scss. This same rule applies to the legacy stylesheets; these fragments are called like lookupinput2.frag.css.
When a new fragment is added you need (for now) to copy the style.theme.scss file and add the includes for the new fragments. In a later version the fragments will be located and included automatically.
Styling a component
Each component must have an unique CSS class "base name". These names usually start with "ui-" followed by a 3 to 5 letter abbreviation for the component's name. For example: the LookupInput component uses ui-lui as its base name. All classes added to html nodes should always starts with this css base name. Using the base name prevents name clashes when different components define the same class name, leading to oddities in rendering.
The root node for the component must define itself to have as its class the CSS base name. This ensures that all components can always be addressed by a CSS class - even when there is no apparent need, yet. The root node may have multiple classes, as long as:
- They all start with the CSS base name (or ARE the CSS base name)
- The CSS base name is ALWAYS present.
An example css structure for a simple DomUI button component could look like this:
<button class='ui-gbtn'> <span class='ui-gbtn-icon'></span> <span class='ui-gbtn-label'>He<span class='ui-gbtn-accel'>l</span>lo</span> </button
All of the styles for a component must be assigned using CSS. Components should never contain code that hard sets the css attributes for the component. The only exception to this rule is when there is no other way to effect what is needed. Adding CSS related code inside the Java code makes the UI very hard to maintain.
Sharing styles
Components should never use classes from other components to handle their styling!! That would lead to very hard to maintain code: changing the style for one component now suddenly has an effect on some other component, and the styles were not designed for that in the first place!
You can define shared styles, but these should be clearly marked as such and be present in a separate stylesheet fragment. Shared styles have no CSS base name suffix.
Shared styles should normally only be used for small things, because sharing too much means that it becomes hard to change components using that style.
Layout rules
One of the biggest design flaws in the earlier DomUI style sheets have to do with layout. So in the new style sheets we attempt to do better, by defining stricter rules.