Reference: quell-core

quell

quell Core v1.0.0

Overview & System Role

quell-core.css is the unlayered reference theme sheet and formal override surface that sits directly above quell-base.css in the Quell cascade contract.

Load Order

  1. quell-base.css (foundation, ghost_tokens, normalization, framework layers)
  2. quell-core.css (reference theme + override surfaces)
  3. Brand/theme implementations (example: quell-light.css)
  4. Application-specific styles

Why It Wins Without !important

Quell uses modern cascade architecture instead of specificity escalation:

Mechanism Result
Surface A tokens outside layers Override layered token values automatically
Surface B layer append Extends named layers without selector inflation
Surface C unlayered selectors Outrank all layered rules regardless of specificity
:where() selectors Zero specificity overhead
No !important Predictable override behavior

Rationale

The system separates cascade control from selector specificity. Overrides occur through layer ordering and token replacement rather than selector wars.

Override Surface Matrix

Override Channel Specificity Cost Primary Target Elements Core Architectural Purpose Target Volume / Chapter
Surface A — Token Override 0 Design tokens Theme replacement Tokens & Theming
Surface B — Layer Append Varies by selector Framework layers Extend existing architecture Cascade Layers
Surface C — Unlayered Rules Selector-native Components Guaranteed downstream wins Component Architecture

Token System Deep-Dive

Font Architecture

Family Style Weight Range Display
Fraunces Normal 100–900 swap
Fraunces Italic 100–900 swap
Nunito Normal 300–900 swap
Nunito Italic 300–900 swap
JetBrains Mono Normal 300–800 swap
JetBrains Mono Italic 300–800 swap

Rationale

Fonts are loaded before token declaration so typography tokens resolve immediately and avoid layout instability.

Typography Tokens

Token Value
--font-fam-primary "Nunito", "Calibri", "Trebuchet MS", sans-serif
--font-fam-secondary "Fraunces", "Georgia", "Garamond", "Times New Roman", serif

Rationale

Primary typography optimizes readability while secondary typography provides editorial hierarchy.

Accent System

Token Value
--color-accent #ff3d40
--color-accent-hover oklch(65.735% 0.2289 25.532 / 0.8)
--color-accent-subtle rgba(255, 61, 64, 0.1)
--shadow-focus 0 0 0 3px rgba(255, 61, 64, 0.35)

Rationale

The accent system centralizes interaction feedback, focus visibility, hover states, alerts, and action affordances.

Surface & Text Tokens — Light Mode

Token Value
--color-surface #f2f2f4
--color-surface-subtle #f4f7f9
--color-surface-raised #f2f2f4
--color-text-primary #191970
--color-text-secondary #35454f
--color-text-muted #616b7e
--color-text-inverse #f2f2f4
--color-border #dddddd
--color-border-strong #cccccc

Surface & Text Tokens — Dark Mode

Media query: @media (prefers-color-scheme: dark)

Token Value
--color-surface #121245
--color-surface-subtle #05052e
--color-surface-raised #1e1e5a
--color-text-primary #f2f2f4
--color-text-secondary #eeeeee
--color-text-muted #616b7e
--color-text-inverse #05052e
--color-border #35428f
--color-border-strong #4d616e
--color-accent-subtle rgba(255, 61, 64, 0.125)
--shadow-focus 0 0 0 3px rgba(255, 61, 64, 0.5)

Rationale

Dark mode swaps semantic roles rather than component rules. Components continue referencing the same tokens while values change automatically.

Radius Tokens

Token Value
--radius-sm 0.25rem
--radius-md 0.5rem
--radius-lg 0.75rem
--radius-xl 1rem
--border-radius-sm 0.25rem
--border-radius-md 0.5rem
--border-radius-lg 0.75rem
--border-radius-xl 1rem

Rationale

A friendly rounded geometry establishes a consumer-oriented personality while preserving tokenized replacement capability.

Motion Tokens

Token Value
--duration-fast 0.15s
--duration-base 0.3s
--duration-slow 0.5s
--ease-default ease-in-out

Rationale

Motion is standardized into three interaction tiers: micro, component, and page-level transitions.

Shadow Tokens

Light Mode

Token Value
--shadow-sm 0 0.375rem 0.5625rem -0.25rem oklch(10.668% 0.00001 271.152 / 0.1)
--shadow-md 0 0.5625rem 0.843rem -0.375rem oklch(10.668% 0.00001 271.152 / 0.125)

Dark Mode

Token Value
--shadow-sm 0 0.375rem 0.5625rem -0.25rem oklch(10.668% 0.00001 271.152 / 0.3)
--shadow-md 0 0.5625rem 0.843rem -0.375rem oklch(10.668% 0.00001 271.152 / 0.4), 0 0.25rem 0.5rem -0.375rem oklch(10.668% 0.00001 271.152 / 0.3)

Rationale

Dark surfaces require stronger opacity values to maintain equivalent perceived depth.

Layer Append & Surface C Component Breakdown

Baseline Appends

Smooth Scrolling

Selector:

:where(html)

Property:

scroll-behavior: smooth;

Optional Flow Spacing

Commented opt-in owl selector:

*:where(* + *:not(br, dt, dd, li, tr, td, th, option, optgroup))

Rhythm token:

--spacing-md (0.843rem)

Rationale

:where() contributes zero specificity, allowing future overrides without escalation.

Form Layer Enhancements

Targets:

  • input (excluding checkbox, radio, range, color, hidden)
  • select
  • textarea

Applied Contract

Property Value
display block
width 100%
padding-block var(--spacing-sm)
padding-inline var(--spacing-md)
background var(--color-surface)
color var(--color-text-primary)
border var(--border-width-sm, 0.0625rem)
border-radius var(--border-radius-md, 0.5rem)

Hover State

border-color: var(--color-border-strong)

Focus Visible State

Property Value
outline none
border-color var(--color-accent)
box-shadow var(--shadow-focus)

Placeholder

Property Value
color var(--color-text-muted, #616b7e)
opacity 1

Rationale

Forms become full-width layout primitives with token-driven accessibility and consistent focus visibility.

Utility Appends

.sr-only

Visually hides content while preserving screen reader access.

.not-sr-only

Reverses .sr-only behavior.

.truncate

Property Value
overflow hidden
text-overflow ellipsis
white-space nowrap
Property Value
position absolute
inset-block-start var(--spacing-sm, 0.5625rem)
inset-inline-start var(--spacing-sm, 0.5625rem)
z-index var(--z-index-overlay,1000)
padding var(--spacing-sm,0.5625rem) var(--spacing-md,0.843rem)
border-radius var(--border-radius-md,0.5rem)
background var(--color-accent,#ff3d40)
color var(--color-text-inverse,#f2f2f4)
transform translateY(-200%)

Focus-visible reveals the control with:

transform: translateY(0)

Rationale

Utilities provide accessibility primitives, overflow management, and keyboard navigation support without component coupling.

Surface C Components

.card

Specificity: (0,1,0)

Property Value
width var(--card-width,22.5rem)
background var(--color-surface,#f2f2f4)
border var(--border-width-sm,0.0625rem)
border-radius var(--border-radius-md,0.5rem)
box-shadow var(--shadow-md)
padding var(--spacing-lg,1.265rem)

.card-header

Property Value
padding var(--spacing-xs,0.375rem)
margin-bottom var(--spacing-md,0.843rem)
border-bottom var(--border-width-sm,0.0625rem) solid var(--color-primary-light,#35428f)

.card-body

Property Value
padding var(--spacing-md,0.843rem)

Rationale

Surface C components intentionally live outside layers so they automatically outrank framework defaults while remaining easy to replace downstream.

Key Architectural Decisions

  • Cascade layers replace specificity escalation.
  • Surface A establishes token-first theme.
  • Surface B enables structured framework extension.
  • Surface C provides deterministic component overrides.
  • Semantic tokens enable automatic dark-mode substitution.
  • Variable fonts centralize typography control.
  • Focus-visible states are treated as first-class accessibility primitives.
  • Logical properties (inset-block-start, inset-inline-start, padding-block, padding-inline) improve internationalization and writing-mode compatibility.
  • :where() selectors intentionally preserve a zero-specificity footprint.
  • Unlayered selectors outperform layered rules without requiring !important.
  • The architecture favors composability, predictability, accessibility, and long-term maintainability over selector complexity.

© 2026 Ortiz Design Studio. | quell system documentation.