Skip to content

Design Principles ​

The visual philosophy. These are the reasons behind the token values in the rest of this section.


The problem with how admin panels look ​

Most admin templates optimise for the screenshot on the marketplace listing: heavy gradients, oversaturated colour, chunky shadows, and cards floating on cards. That works for a thumbnail and fails for the eight hours a day someone actually uses the thing.

AdminVora optimises for the eighth hour.


1. Quiet by default, loud on purpose ​

Colour is a scarce resource. It is spent on things that need attention: a destructive action, a failing status, the primary call to action. Everything else is neutral.

ElementTreatment
Page backgroundNeutral 50 (light) / Neutral 950 (dark)
CardsNeutral 0 / 900, 1px subtle border, minimal shadow
Body textNeutral 900 / Neutral 50
Secondary textNeutral 600 / Neutral 400
Brand colourPrimary action, active nav item, focus ring, key data series
Semantic colourStatus only — never decoration

A typical AdminVora screen uses brand colour on under 5% of its pixels. That is what makes the brand colour mean something.

2. Hierarchy through space and weight, not lines and boxes ​

Junior design solves hierarchy with borders. Every card gets a header rule, a footer rule, and a divider between every row. The result is a grid of cages.

AdminVora establishes hierarchy in this order:

1. Whitespace       ← try this first, always
2. Type size & weight
3. Colour (text on surface)
4. Surface elevation
5. Border           ← last resort

Before / after: the same card with 4 dividers versus none but a 24 px section gap reads faster in usability testing and prints better.

3. Density is a user decision ​

An analyst reconciling 500 rows wants small text and tight rows. A manager reviewing five KPIs wants air. Both are right.

Three density modes scale spacing (not font size — that would break the type scale):

ModeMultiplierTable row heightBest for
compact0.8×36 pxData-heavy tools, power users
comfortable1×48 pxDefault
spacious1.25×60 pxDashboards, touch, presentation

4. Motion explains, it never decorates ​

Every animation answers one of three questions:

  1. Where did this come from? (a drawer slides from the edge it belongs to)
  2. What changed? (a value counts up, a row highlights then fades)
  3. Is the system working? (a skeleton pulses, a spinner turns)

If an animation answers none of these, it is deleted. Durations are short — 120–320 ms — because the interface is used thousands of times per day.

Full rules: Motion.

5. Depth is atmospheric, not literal ​

Shadows are not drop shadows from a 45° light source. They are two-layer, low-opacity, tinted with the surface hue, and they get tighter as elevation decreases.

scss
// A single blurry shadow reads as cheap
--av-shadow-md:
  0 1px 2px  -1px oklch(var(--av-shadow-color) / .06),   // contact shadow: tight, defines the edge
  0 4px 12px -2px oklch(var(--av-shadow-color) / .10);   // ambient shadow: soft, gives lift

In dark mode, shadows barely work — there is nothing darker than the background. Dark elevation is communicated with a lighter surface plus a 1px inner top highlight, mimicking how light catches a raised edge.

6. Typography does the heavy lifting ​

Three families, one variable axis each, a strict modular scale. No decorative fonts, no more than three sizes on a typical screen.

  • Numbers are always tabular in tables, KPI values, and anywhere figures stack vertically. A column of proportional digits is unreadable.
  • Line length is capped at 72ch for prose. Full-width paragraphs on a 27" monitor are unreadable.
  • Line height varies by size: 1.2 for display, 1.35 for headings, 1.5 for body, 1.6 for long-form.

Detail: Typography.

7. Every state is designed ​

Empty, loading, error, partial, and success are not edge cases — they are the majority of what users see in a real system.

StateRequirement
EmptyIllustration, one sentence of explanation, and the action that fixes it
LoadingSkeleton matching the real content's shape — never a centred spinner over a blank page
ErrorWhat failed, why, and a retry button. Never a raw stack trace.
PartialShow what loaded; do not block the page on the slowest widget
SuccessConfirm and return focus to a sensible place

Every component in /docs/06-components documents all five.

8. Accessible by construction, not by audit ​

  • Contrast targets are baked into the colour ramp: step 600 on step 50 always clears 4.5:1; step 700 on white always clears 7:1.
  • Focus is a 2 px ring plus a 2 px offset in a colour computed to contrast with the element it surrounds — automatically, in every theme.
  • Nothing is communicated by colour alone. A "success" badge has an icon and a label, not just green.
  • Touch targets are 44 × 44 px minimum, achieved with padding or a pseudo-element expansion, never by making the visible control clumsy.

9. Print is a real output ​

Admin panels get printed: invoices, reports, packing slips. _print.scss is not an afterthought.

scss
@media print {
  .av-sidebar, .av-topbar, .av-footer, .av-drawer,
  [data-av-customizer], .av-page-header__actions { display: none !important; }

  .av-shell  { display: block; }
  .av-content{ padding: 0; }
  .av-card   { border: 1px solid #ccc; box-shadow: none; break-inside: avoid; }
  .av-table  { break-inside: auto; th { break-after: avoid; } }
  a[href^="http"]::after { content: " (" attr(href) ")"; font-size: .75em; }
  @page { margin: 1.5cm; }
}

10. Restraint in effects ​

Glassmorphism, gradients, glows, and grain exist in the system — as opt-in utilities, never defaults. They are correct on a login screen, a pricing page, or a marketing surface. They are wrong on a table of 500 invoices.

EffectUtilityAppropriate for
Glass blur.av-glassAuth screens, overlays on imagery, floating navbars
Gradient border.av-border-gradientFeatured/premium cards
Gradient text.av-text-gradientOne hero headline per page, maximum
Spotlight hover.av-spotlightPricing cards, feature grids
Grain overlay.av-grainLarge empty hero areas
Glow.av-glowDark-mode CTAs only

Reviewers reject any PR that applies these to data-dense surfaces.


The eye test ​

Before shipping a screen, ask:

  1. Squint at it. Does the most important thing still stand out? If everything is equally prominent, nothing is.
  2. Print it in greyscale. Is anything now ambiguous? If yes, colour is carrying meaning alone.
  3. Zoom to 200%. Does it still work? (WCAG 1.4.4 requires it.)
  4. Load it at 360 px wide. Is there horizontal scroll? There must not be.
  5. Toggle dark mode. Does anything glow, vibrate, or disappear?
  6. Count the fonts, weights, and sizes. More than 3 / 4 / 5 on one screen means cutting is due.
  7. Remove every border. Does it still read? If yes, keep it that way.

Read next: Design Tokens.

Documentation for @creativeigniter/adminvora