Shadows · Docs · PyColors

Design SystemShadows

OverviewLink to section

Shadows define depth and hierarchy in the interface.

In PyColors, elevation is intentionally subtle. The goal is not visual drama, but predictable structure.

A controlled shadow system ensures that:

surfaces feel layered without noise
focus states are clear
overlays feel intentional
the UI remains calm and readable

Why this matters

When shadows are inconsistent or too strong, interfaces feel noisy and unstructured. A restrained elevation system improves clarity and perceived quality.

What you’ll defineLink to section

Elevation scale

A small set of shadow levels used across all surfaces.

Usage rules

Clear constraints to avoid visual noise and inconsistency.

Surface hierarchy

Define how components relate visually through depth.

StepsLink to section

Use a limited elevation scaleLink to section

PyColors defines a small set of shadow tokens:

Token	Typical use
`shadow-xs`	buttons, inputs, small controls
`shadow-sm`	default cards and surfaces
`shadow-md`	popovers, dropdowns
`shadow-lg`	modals and overlays

Each level increases elevation gradually.

Apply shadows consistentlyLink to section

shadow-xs

Small controls

shadow-sm

Default cards

shadow-md

Popovers

shadow-lg

Modals

components/shadow-preview.tsx

export function ShadowPreview() {
  return (
    <div className="grid gap-4 sm:grid-cols-2">
      <div className="rounded-lg border bg-card p-4 shadow-xs">
        shadow-xs
      </div>

      <div className="rounded-lg border bg-card p-4 shadow-sm">
        shadow-sm
      </div>

      <div className="rounded-lg border bg-card p-4 shadow-md">
        shadow-md
      </div>

      <div className="rounded-lg border bg-card p-4 shadow-lg">
        shadow-lg
      </div>
    </div>
  );
}

Avoid custom shadowsLink to section

Do not introduce custom box-shadow values inside components.

Instead:

reuse existing tokens
extend the system if necessary
keep visual hierarchy predictable

System rule

If a new shadow is needed more than once, it should become a token.

Decision guideLink to section

Use this system if:

you need consistent elevation across multiple surfaces
you are building dashboards or SaaS products
you want predictable layering behavior
you want UI clarity without visual overload

Avoid if:

the shadow is decorative only
it breaks the system scale
it duplicates an existing token
it creates visual noise

Prefer

use predefined shadow tokens
keep elevation subtle
increase depth only when needed
align shadow with radius and surface

Avoid

stacking multiple shadows
high contrast or heavy shadows
custom box-shadow per component
inconsistent elevation levels

Why it mattersLink to section

Shadows are one of the fastest ways to break visual consistency.

too many shadows → noisy UI
too strong shadows → cheap look
inconsistent shadows → broken hierarchy

A controlled system ensures:

clarity
structure
visual calm
perceived product quality