A few arbitrary tips on Omeka-S theming.

Retain existing classes on analogous elements as far as possible, as they are sometimes referred to by internal Omeka CSS classes. Obviously you can imagine edge cases where this isn't desirable. But it's a good first rule to follow. Obviously if you omit some design-element entirely you must also omit the class associated with it.

In a similar vein, be wary of doing less than the requirements of a theme. There's no real verification or way of testing that a theme handles all paths sensibly and in a manner consistent with the expectations of the user.

For example, there are certain site settings your theme should support: "embed media on item page" is a site specific setting that you must handle within your theme, but there is no validation that your theme does in fact handle this.

Do not ever use <p></p> elements in your module markup. Use custom divs or spans with your own classes. Why? The Html blocklayout generates <p> tags, so any attempt to style page text will often inadvertently style your more-irregular p tags.

Config form names should be in snake_case.

Debugging templates: a very rudimentary debugging method is to fill your partials with introductory HTML comments naming their source file.

Eg:

<!-- BEGIN view/omeka/site/item/show.phtml -->
<p>This is content this is content this is content</p>
<!-- END view/omeka/site/item/show.phtml -->

One way to modularize your CSS is to break out the per-page CSS into individual CSS files, then include them in layout.phtml

$this->headLink()->appendStylesheet($this->assetUrl('css/style.css'));
$this->headLink()->appendStylesheet($this->assetUrl('css/item-show.css'));

Here, item-show.css contains rules associated to the item detail page.

Don't try to remove these from your layout.phtml. These are internal Omeka files that in turn may cause the loading of more than one JS file.

$this->headScript()->prependFile($this->assetUrl('js/global.js', 'Omeka'));
$this->headScript()->prependFile($this->assetUrl('vendor/jquery/jquery.min.js', 'Omeka'));

If you need to style the 'page title' block which is available in the page editor, you don't have a lot of good options, because it's not addressable by any specific CSS style. You just have the choice to do the following:

.my-page-content > .blocks > h2 {
    background-color: var(--accent2);
    text-align: center;
    font-family: "Quicksand Bold";
    padding: 1em 1em;
    margin: 0 0;
    margin-bottom: 1em;
}

Where my-page-content is a class applied to the page content using an override on view/omeka/site/page/show.phtml. .blocks is created by the framework. You have to just assume that every h2 block is a page title -- this means your own modules and markup can't generally use h2; you must stick to div and theme-specific classes.