Design & quality guidelines

Design & quality guidelines#

A theme can pass every technical check — ship all required files, resolve every page, preserve every Livewire binding — and still look cheap. The difference between a storefront that reads as a premium product and one that reads as generated is not a framework or a feature. It is a small set of restraints, applied everywhere without exception.

These are portable guidelines. They are written to hold for any Salieno theme, whatever palette or personality you give it — not just the first-party reference. Where a rule cites a concrete value, that value comes from the reference theme's stylesheet (resources/views/themes/salieno/assets/css/salieno.css); treat the principle as the rule and the number as one worked example.

The through-line: be deliberate, and be consistent. A page reads as designed when every choice looks like it was made once, on purpose, and reused. It reads as generated when it looks like a dozen small choices were made independently.

1. Your accent colour is for action and state — never decoration#

Pick one accent (the reference uses red, #ef4444, exposed as theme.json → colors.primary). That colour earns its saliency by being rare and by always meaning the same thing: this is something you can do, or something the system is telling you.

Legitimate uses:

• Solid call-to-action buttons and their hover/active state
• :focus-visible rings
• Status and value chips that carry real meaning — FEATURED, SAVE 15%
• A single restrained section glow

Never use it as ornament:

• No coloured eyebrows or section kickers
• No coloured icons, glyphs, or category tiles
• No coloured checkmarks — a tick means success, and success is green, not your brand colour
• No coloured headline words, step numbers, currency symbols, or quote marks

The reason is mechanical: every decorative accent competes with the one accent that is actually a target, and the eye can only be pulled toward one thing per screen. Nine separate times during the reference theme's own design pass, the same fault crept back in — a red eyebrow here, a red icon there — each one quietly stealing attention from the buy button three inches below it.

{{-- Don't: the accent as decoration --}}
<p class="eyebrow text-primary-600 dark:text-primary-400">Managed hosting</p>
<i class="ph ph-check text-primary-500"></i> SSD storage

{{-- Do: neutral label, semantic tick, accent saved for the CTA --}}
<p class="mono-eyebrow">Managed hosting</p>
<i class="ph ph-check text-emerald-500" aria-hidden="true"></i> SSD storage

How to apply it to your own theme: before you ship, classify every use of your accent by role. If it isn't a button, a focus ring, a genuine status, or the one section glow, make it neutral. Do not colour-match sweep — that destroys real badges and states along with the decoration. Classify first, then neutralize.

2. One restrained type ladder#

Decide your text styles once and reuse them. The reference theme aims for roughly eight distinct text styles per section and uses only three weights — 400, 500, 600. Nothing renders below 10px. Headings resolve from a single token per rung (for example --text-h2: clamp(1.75rem, 3vw, 2.5rem)), so a heading is the same size everywhere it appears.

• Cap your weights. Two or three is a system; five is noise. If you find yourself reaching for a heavier weight to make something stand out, the problem is usually spacing or hierarchy, not weight.
• One token per rung. Define your display / h1 / h2 / body sizes as CSS variables or Tailwind theme tokens and reference them. Never hand-set a font size at a call site — that is how you end up with 46 near-identical sizes (13px, 13.5px, 14px, 14.5px…) that read as sloppy up close.
• No gradient text. bg-clip-text on a headline is a reliable tell. Set a colour.
• Floor at ~10px so labels stay legible. Remember that SVG font-size is in user units, not pixels — a font-size="10" inside a 600-wide viewBox scaled into a narrow column can render well under the floor (see Sections for the viewBox math).

3. The neutral mono micro-label is your signature#

The single most reliable craft signal across the Salieno ecosystem is the eyebrow / micro-label: a small, uppercase, letter-tracked, neutral label in a monospace face, set as bare text — no pill, no dot, no border, no accent colour.

.mono-eyebrow {
    font-family: ui-monospace, monospace;
    text-transform: uppercase;
    font-size: 12px;
    font-weight: 500;
    letter-spacing: 0.2em;
    color: #6a6a75; /* a muted subtle-foreground token, never the brand colour */
}

<p class="mono-eyebrow">Managed hosting</p>
<h2 class="section-title">Everything runs on NVMe</h2>

The anti-pattern it replaces — a tinted pill containing a coloured dot and a coloured mono label — is, in the reference author's own words, "the biggest style tell vs the reference." Repeating that one ornament at the top of every section is exactly what makes a page look machine-produced rather than composed. A bare neutral eyebrow does the same job (it labels the section) with none of the tell.

Pair it with a matching micro count where a section header wants a secondary figure (13 features, 4 modules) set in the same mono family, right-aligned against the title. The combination — title left, muted mono figure right — is a clean, repeatable header pattern you can use on every section.

4. Elevation from value and one hairline — not many borders#

Depth should come from surface value and a single shadow, not from stacking bordered boxes. The reference builds every card the same way:

• a surface that is genuinely lighter than the canvas (#111114 card on #08080a canvas in dark; #ffffff on #f4f4f5 in light)
• one barely-there hairline — rgba(255,255,255,0.07) in dark, #e4e4e7 in light
• one soft shadow
• a small radius — 10px, not 16px+

/* Dark card */
background: #111114;
border: 1px solid rgba(255, 255, 255, 0.07);
border-radius: 10px;
box-shadow: 0 12px 28px -8px rgba(0, 0, 0, 0.45);

What to avoid: stacked bordered panels, filled header and footer bars inside a card, and loud opaque grey outlines. That chrome is what cPanel and WHMCS tables look like, and it is precisely the aesthetic a premium theme is trying to escape. When you have a list of items, don't box each one — put them on the canvas and separate them with divide-y hairlines and space. Reserve the elevated card for the one thing you want to lift off the page (the featured plan, the primary panel).

Two practical traps when you build this:

• Keep radii at or below the framework defaults. In Tailwind v4, your --radius-* theme tokens redefine the rounded-lg / rounded-xl utilities. Set lg above the default and every corner in the theme doubles, and monotonicity breaks (rounded-xl can render larger than rounded-2xl).
• If you ship precompiled CSS, every hairline class you use must be in the bundle. A dark:border-white/[0.08] that never got compiled silently falls back to a bright light-mode grey border on your dark surfaces. See Assets on precompiled bundles.

5. Illustrations depict a real mechanism#

If you draw anything, it must explain something. The test is simple: remove the heading above the illustration. If the drawing still communicates what the section is about, it depicts a mechanism. If it becomes meaningless, it was decoration.

• Don't draw orbit rings, concentric spinning circles, scattered pulsing dots, gradient arcs, or generic "tech" chrome. These are the visual equivalent of filler.
• Do draw the actual thing the copy is about — what moves during a migration (files, database, mail, DNS), what root access is (a shell with real commands), what isolation is (a boundary line between tenants). Labelled cards and connectors beat a pretty gradient every time.

Two accessibility musts on any decorative SVG:

• Mark purely decorative graphics aria-hidden="true" so screen readers skip them; give meaningful diagrams a <title> and role="img".
• Drive animation with CSS (offset-path + offset-distance, or plain transitions), not SMIL. <animateMotion> cannot be stopped by prefers-reduced-motion, and honouring reduced-motion is not optional.

6. Accessibility is part of the design, not a later pass#

A premium theme is usable by everyone. Build these in from the start:

• Contrast meets WCAG AA — 4.5:1 for body text, 3:1 for large text and meaningful UI. Test both themes. A muted grey that reads fine on light can fail on dark, and vice versa. Never set body copy in a muted foreground token; muted is for secondary text only.
• Visible focus. Every interactive element gets one consistent ring, declared once. The reference sets it globally and lets nothing else draw its own:

  :focus-visible {
      outline: 2px solid var(--primary);
      outline-offset: 2px;
      border-radius: 4px;
  }

• Touch targets ≥ 44px. Buttons and tappable controls need a real minimum height. The reference floors buttons at 48px. Gate the floor on pointer type, not viewport width — @media (pointer: coarse) — because a 640px tablet is still a finger and a 380px desktop window is still a mouse.
• Never hide a control behind hover on touch. sm:opacity-0 sm:group-hover:opacity-100 makes a button invisible forever on a touch device wide enough to trip the breakpoint. Reveal-on-hover must be gated on @media (hover: hover) and (pointer: fine), never on width.
• `aria` on decorative glyphs, labels on icon-only buttons, real <label>s (or aria-label) on every input.

7. Mobile-first and no horizontal overflow#

Design the narrow layout first, then let it grow. The page body must never scroll sideways at any width down to 320px — wide content (tables, code, wide diagrams) scrolls inside its own overflow-x: auto container, not the page.

The one mobile rule people miss: iOS Safari auto-zooms any form control whose font-size is below 16px on focus, and does not zoom back out. Ad-hoc inputs at text-sm (14px) are the usual culprit. Ship one unlayered rule so no input can trip it:

@media (max-width: 639.98px) {
    input:not([type='checkbox']):not([type='radio']):not([type='range']):not([type='color']),
    select,
    textarea {
        font-size: 16px;
    }
}

Desktop keeps its denser 14px; mobile gets 16px and stops zooming. The rule is unlayered on purpose so it beats the framework's layered text utilities without !important.

8. Consistency: one of each thing#

This is the rule that ties the rest together, and the one that most separates designed from assembled.

• One card style. Every card in the theme is the same surface, hairline, radius, and shadow. If you have two card recipes, you have a bug.
• One button system. One primary, one secondary, one ghost — each with a single defined height, padding, and focus ring. Four competing button recipes is the classic tell of a page built section by section without a system.
• One background per page. Do not alternate grey / white / grey between sections to "break things up" — that stripe pattern is generated-looking. Give the page one canvas and create rhythm with spacing and content, not by repainting the floor.
• Consistent section rhythm. Use one vertical spacing scale (the reference runs roughly py-24 sm:py-32 lg:py-40) so every section breathes the same way.

When the storefront's own pages were audited against the homepage as the source of truth, the theme was found to be highly consistent already — precisely because it reused one card, one button system, one eyebrow, one background. The one divergence that stood out was a competing eyebrow style. That is the level of consistency to hold yourself to: a single stray pattern should be conspicuous.

9. Light and dark parity#

If your theme.json declares supports.dark_mode: true, both modes are first-class — not a real design and an afterthought. Every rule above holds in both. Define your palette as tokens and swap only the token values between modes; never let a colour exist only in one mode's block. Check contrast, hairline visibility, and shadow legibility in each. A shadow that reads as depth on light can vanish on dark, so the dark surface leans harder on value contrast and the hairline. See Colours, dark mode & the mode switcher for wiring the switch and the token structure.

The quality bar, in one line#

Make every choice once, on purpose, and reuse it. Save your accent for action. Keep type, cards, and buttons to one of each. Draw only what explains something. Meet WCAG, floor your touch targets, and never overflow. Do it identically in light and dark. A theme that holds all of that reads as a product someone built — which is the whole point.

Next#

You now have the design bar and the full mechanics of a Salieno theme. Return to any topic you need: pages, sections, components, or the helper reference — and when you are ready to ship, Testing your theme and Publishing & updating on the marketplace.