Color

Name the role, not the color. A semantic role (--magma-*) says what an element is, a raised card, muted text, the primary action, and resolves to a color for the mode, the named theme and the contrast preference of the page. A palette step only flips with the mode: it stays grey under a tinted theme and gains no contrast when the user asks for more.

Two ways to write a role

Every role is a custom property holding rgb channels, and a Tailwind color.

.panel {
  background: rgb(var(--magma-surface-raised));
  color: rgb(var(--magma-text-default));
  border: 1px solid rgb(var(--magma-border-muted));
}

<section class="bg-surface-raised text-fg-default border border-border-muted">
  <p class="text-fg-muted">Secondary text</p>
</section>

In Tailwind the text roles are fg-*, so that no class reads text-text-*: --magma-text-muted is text-fg-muted. Every other role keeps its name. The roles come from styles/dist/css/semantic.css, their Tailwind colors from styles/dist/tailwind/theme.css; an opacity modifier works as usual (bg-surface-raised/80).

Neutral roles

The backgrounds, text and borders of everything that is neither an action nor a state. A named theme retints all of them at once.

Surfaces

Five levels, chosen by where the element sits, not by the shade: default is the page, sunken is recessed into it (wells, code blocks, tracks), muted groups on the page plane (zebra rows), raised is lifted off it (cards, panels, sticky bars), overlay floats above everything (modals, dropdowns, popovers). In light mode the levels above the page are close, so give raised and overlay a shadow too, as the components do.

--magma-surface-sunken

bg-surface-sunken

#e8e8e8

alias of --surface-neutral-sunken

#020202

Below the page: wells, insets, code blocks, tracks.

--magma-surface-muted

bg-surface-muted

#ebebeb

alias of --surface-neutral-muted

#0d0d0d

Same-plane grouping on the page: zebra rows, a subtle section.

--magma-surface-default

bg-surface-default

#f2f2f2

alias of --surface-neutral-default

#1d1d1d

The page canvas, the background of the body.

--magma-surface-raised

bg-surface-raised

#f8f8f8

alias of --surface-neutral-raised

#303030

Above the page: cards, panels, sticky headers.

--magma-surface-overlay

bg-surface-overlay

#ffffff

alias of --surface-neutral-overlay

#4a4a4a

Floating above everything: modal, dropdown, popover, sheet.

--magma-surface-inverse

bg-surface-inverse

#2a2a2a

alias of --tone-neutral-02

#f4f4f4

A chip that flips with the mode: dark on a light page, light on a dark one.

--magma-surface-inverse-muted

bg-surface-inverse-muted

#494949

alias of --tone-neutral-03

#e4e4e4

The inverse chip, one step quieter.

Wash

A neutral pill, chip or hover, by how marked it is. wash-soft carries the whole text ladder, wash-base only text-default, wash-strong only icons.

--magma-wash-soft

bg-wash-soft

#ededed

alias of --tone-neutral-10

#3e3e3e

A neutral pill or chip, the least marked.

--magma-wash-base

bg-wash-base

#e1e1e1

alias of --tone-neutral-09

#535353

A neutral pill or chip, at its default prominence.

--magma-wash-strong

bg-wash-strong

#d0d0d0

alias of --tone-neutral-08

#6b6b6b

A neutral pill or chip, the most marked.

Text

text-muted is for secondary text that is still essential, text-subtle only for what the user can skip. Every text role is legible on all five surfaces in both modes.

--magma-text-default

text-fg-default

#050505

alias of --text-neutral-default

#fcfcfc

Body text, titles and primary data.

--magma-text-muted

text-fg-muted

#494949

alias of --text-neutral-muted

#e4e4e4

Secondary text that is still essential, such as an address or a phone number.

--magma-text-subtle

text-fg-subtle

#636363

alias of --text-neutral-subtle

#d3d3d3

Non-essential text only: captions, units, hints.

--magma-text-disabled

text-fg-disabled

#777777

alias of --text-neutral-disabled

#c4c4c4

The labels of disabled controls.

--magma-text-on-emphasis

text-fg-on-emphasis

#ffffff

alias of --tone-neutral-seed

#1d1d1d

Text and icons on a solid fill.

Borders

border-muted is decorative (dividers, table grids), border-default outlines what works (inputs, cards), border-strong conveys a state, border-focus follows the accent.

--magma-border-muted

border-border-muted

#dbdbdb

alias of --border-neutral-muted

#404040

Decorative borders: dividers, the grid of a table.

--magma-border-default

border-border-default

#c4c4c4

alias of --border-neutral-default

#6f6f6f

Functional outlines: inputs, cards.

--magma-border-strong

border-border-strong

#8c8c8c

alias of --border-neutral-strong

#ababab

A border that conveys a state, such as selected.

--magma-border-focus

border-border-focus

#2467e7

alias of --brand-maggioli-04

#becade

Focus indication; follows the accent.

Other neutral roles

The inverse chip and its ink, the ink on the modal scrim, the selection, and the color of a projected shadow, to compose with your own geometry and alpha. --magma-neutral-emphasis and --magma-neutral-on-emphasis are deprecated aliases of --magma-surface-inverse and --magma-on-inverse.

--magma-shadow-ink

shadow-shadow-ink

#050505

alias of --tone-neutral-01

#fcfcfc

The colour of a projected shadow, to compose with your own geometry and alpha.

--magma-neutral-fg

text-neutral-fg

#494949

alias of --tone-neutral-03

#e4e4e4

Neutral text and icons on a coloured context.

--magma-neutral-border

border-neutral-border

#a5a5a5

alias of --tone-neutral-06

#9a9a9a

A neutral border on a coloured context.

--magma-neutral-emphasis

bg-neutral-emphasis

#2a2a2a

alias of --tone-neutral-02

#f4f4f4

Deprecated: the inverse surface under its old name.

--magma-neutral-on-emphasis

text-neutral-on-emphasis

#ffffff

alias of --tone-neutral-seed

#1d1d1d

Deprecated: the ink on the inverse surface under its old name.

--magma-on-inverse

text-on-inverse

#ffffff

alias of --tone-neutral-seed

#1d1d1d

Text and icons on either inverse surface.

--magma-on-backdrop

#fcfcfc

--magma-selection-background

#b9e7fb

alias of --label-sky-09

#08597e

--magma-selection-color

#043044

alias of --label-sky-01

#e5f6fd

Accents

Two accents with the same nine roles: accent, the action color of the brand, and accent-ai, for features driven by AI. -fg is ink on a neutral surface, -on-emphasis is ink on the solid fill: swapping them is the quickest way to break contrast.

Accent

--magma-accent-surface

bg-accent-surface

#dce0e7

alias of --brand-maggioli-09

#0446c3

A background tinted with the brand accent: a selected row or chip.

--magma-accent-fg

text-accent-fg

#074ccc

alias of --brand-maggioli-03

#d5dae4

Text or an icon in the brand accent on a neutral surface, such as a link.

--magma-accent-border

border-accent-border

#94acda

alias of --brand-maggioli-06

#6e94dc

A border tinted with the brand accent.

--magma-accent-emphasis

bg-accent-emphasis

#2467e7

alias of --brand-maggioli-04

#becade

The solid fill of the brand accent: the primary action.

--magma-accent-emphasis-hover

bg-accent-emphasis-hover

#074ccc

alias of --brand-maggioli-03

#d5dae4

The solid fill of the brand accent, hovered.

--magma-accent-emphasis-active

bg-accent-emphasis-active

#0039a3

alias of --brand-maggioli-02

#e4e6eb

The solid fill of the brand accent, pressed.

--magma-accent-surface-hover

bg-accent-surface-hover

#ccd4e2

alias of --brand-maggioli-08

#1058e0

A background tinted with the brand accent, hovered.

--magma-accent-surface-subtle

bg-accent-surface-subtle

#ecedf0

alias of --brand-maggioli-10

#003393

A background tinted with the brand accent, lighter.

--magma-accent-on-emphasis

text-accent-on-emphasis

#ffffff

alias of --tone-neutral-seed

#1d1d1d

Text and icons on the solid fill of the brand accent.

AI accent

--magma-accent-ai-surface

bg-accent-ai-surface

#e5dafd

alias of --label-violet-09

#500de8

A background tinted with the AI accent: a selected row or chip.

--magma-accent-ai-fg

text-accent-ai-fg

#5714f2

alias of --label-violet-03

#e0d3fd

Text or an icon in the AI accent on a neutral surface, such as a link.

--magma-accent-ai-border

border-accent-ai-border

#b89cfa

alias of --label-violet-06

#a47ef8

A border tinted with the AI accent.

--magma-accent-ai-emphasis

bg-accent-ai-emphasis

#7e49f5

alias of --label-violet-04

#d2c0fc

The solid fill of the AI accent: the primary action.

--magma-accent-ai-emphasis-hover

bg-accent-ai-emphasis-hover

#5714f2

alias of --label-violet-03

#e0d3fd

The solid fill of the AI accent, hovered.

--magma-accent-ai-emphasis-active

bg-accent-ai-emphasis-active

#410bbe

alias of --label-violet-02

#ebe2fd

The solid fill of the AI accent, pressed.

--magma-accent-ai-surface-hover

bg-accent-ai-surface-hover

#dbcdfc

alias of --label-violet-08

#6f35f4

A background tinted with the AI accent, hovered.

--magma-accent-ai-surface-subtle

bg-accent-ai-surface-subtle

#f0eafe

alias of --label-violet-10

#3b09ab

A background tinted with the AI accent, lighter.

--magma-accent-ai-on-emphasis

text-accent-ai-on-emphasis

#ffffff

alias of --tone-neutral-seed

#1d1d1d

Text and icons on the solid fill of the AI accent.

Status

Info, success, warning and danger publish the same vocabulary: washes with their text, borders, a solid fill with its ink, and three shortcuts at the default prominence (-surface, -fg, -border). The danger role uses the status-error palette. A named theme never retints a status; the contrast preference promotes its text.

Info

--magma-info-wash-soft

bg-info-wash-soft

#dcf0fa

alias of --status-info-10

#003f69

The info background, the least marked.

--magma-info-wash-base

bg-info-wash-base

#c1e6f6

alias of --status-info-09

#005883

The info background, at its default prominence.

--magma-info-wash-strong

bg-info-wash-strong

#a8dbf2

alias of --status-info-08

#006b97

The info background, the most marked: icons only, no essential text.

--magma-info-text-default

text-info-fg-default

#002d56

alias of --text-info-default

#e8f5fc

Info text on the info background.

--magma-info-text-muted

text-info-fg-muted

#004772

alias of --text-info-muted

#cfebf8

Secondary info text on the info background.

--magma-info-text-subtle

text-info-fg-subtle

#005e89

alias of --text-info-subtle

#b4e0f4

Non-essential info text on the info background.

--magma-info-text-disabled

text-info-fg-disabled

#008ab8

alias of --text-info-disabled

#70c6ea

Disabled info text on the info background.

--magma-info-border-muted

border-info-border-muted

#b8e2f5

alias of --border-info-muted

#004970

The decorative info border.

--magma-info-border-default

border-info-border-default

#8dcfeb

alias of --border-info-default

#007ca8

The functional info border.

--magma-info-border-strong

border-info-border-strong

#129ac4

alias of --border-info-strong

#5eb8dc

The info border that conveys a state.

--magma-info-emphasis

bg-info-emphasis

#0077a4

alias of --status-info-04

#91d2ef

The solid info fill: a solid badge, a button.

--magma-info-emphasis-hover

bg-info-emphasis-hover

#005e89

alias of --status-info-03

#b4e0f4

The solid info fill, hovered.

--magma-info-emphasis-active

bg-info-emphasis-active

#004772

alias of --status-info-02

#cfebf8

The solid info fill, pressed.

--magma-info-on-emphasis

text-info-on-emphasis

#ffffff

alias of --tone-neutral-seed

#1d1d1d

Text and icons on the solid info fill.

--magma-info-surface

bg-info-surface

#c1e6f6

alias of --status-info-09

#005883

Shortcut for the info background at its default prominence (wash-base).

--magma-info-fg

text-info-fg

#002d56

alias of --text-info-default

#e8f5fc

Shortcut for the default info text (text-default).

--magma-info-border

border-info-border

#8dcfeb

alias of --border-info-default

#007ca8

Shortcut for the functional info border (border-default).

Success

--magma-success-wash-soft

bg-success-wash-soft

#dcf3e3

alias of --status-success-10

#004800

The success background, the least marked.

--magma-success-wash-base

bg-success-wash-base

#bfe9cd

alias of --status-success-09

#00611b

The success background, at its default prominence.

--magma-success-wash-strong

bg-success-wash-strong

#a5e1ba

alias of --status-success-08

#00742e

The success background, the most marked: icons only, no essential text.

--magma-success-text-default

text-success-fg-default

#003500

alias of --text-success-default

#e7f7ec

Success text on the success background.

--magma-success-text-muted

text-success-fg-muted

#005007

alias of --text-success-muted

#ceeed8

Secondary success text on the success background.

--magma-success-text-subtle

text-success-fg-subtle

#006620

alias of --text-success-subtle

#b3e6c4

Non-essential success text on the success background.

--magma-success-text-disabled

text-success-fg-disabled

#00944c

alias of --text-success-disabled

#6bce93

Disabled success text on the success background.

--magma-success-border-muted

border-success-border-muted

#b9e8c9

alias of --border-success-muted

#005514

The decorative success border.

--magma-success-border-default

border-success-border-default

#8fd7a9

alias of --border-success-default

#008941

The functional success border.

--magma-success-border-strong

border-success-border-strong

#11a662

alias of --border-success-strong

#5fc388

The success border that conveys a state.

--magma-success-emphasis

bg-success-emphasis

#008039

alias of --status-success-04

#8fd9aa

The solid success fill: a solid badge, a button.

--magma-success-emphasis-hover

bg-success-emphasis-hover

#006620

alias of --status-success-03

#b3e6c4

The solid success fill, hovered.

--magma-success-emphasis-active

bg-success-emphasis-active

#005007

alias of --status-success-02

#ceeed8

The solid success fill, pressed.

--magma-success-on-emphasis

text-success-on-emphasis

#ffffff

alias of --tone-neutral-seed

#1d1d1d

Text and icons on the solid success fill.

--magma-success-surface

bg-success-surface

#bfe9cd

alias of --status-success-09

#00611b

Shortcut for the success background at its default prominence (wash-base).

--magma-success-fg

text-success-fg

#003500

alias of --text-success-default

#e7f7ec

Shortcut for the default success text (text-default).

--magma-success-border

border-success-border

#8fd7a9

alias of --border-success-default

#008941

Shortcut for the functional success border (border-default).

Warning

--magma-warning-wash-soft

bg-warning-wash-soft

#ffedb5

alias of --status-warning-10

#4f3b00

The warning background, the least marked.

--magma-warning-wash-base

bg-warning-wash-base

#ffdc75

alias of --status-warning-09

#6b5000

The warning background, at its default prominence.

--magma-warning-wash-strong

bg-warning-wash-strong

#ffcd39

alias of --status-warning-08

#816000

The warning background, the most marked: icons only, no essential text.

--magma-warning-text-default

text-warning-fg-default

#3a2c00

alias of --text-warning-default

#fff2cd

Warning text on the warning background.

--magma-warning-text-muted

text-warning-fg-muted

#584200

alias of --text-warning-muted

#ffe595

Secondary warning text on the warning background.

--magma-warning-text-subtle

text-warning-fg-subtle

#715500

alias of --text-warning-subtle

#ffd559

Non-essential warning text on the warning background.

--magma-warning-text-disabled

text-warning-fg-disabled

#a47b00

alias of --text-warning-disabled

#edb100

Disabled warning text on the warning background.

--magma-warning-border-muted

border-warning-border-muted

#efd8a8

alias of --border-warning-muted

#653100

The decorative warning border.

--magma-warning-border-default

border-warning-border-default

#e2bf75

alias of --border-warning-default

#9b6200

The functional warning border.

--magma-warning-border-strong

border-warning-border-strong

#b88200

alias of --border-warning-strong

#d1a337

The warning border that conveys a state.

--magma-warning-emphasis

bg-warning-emphasis

#8e6a00

alias of --status-warning-04

#febe00

The solid warning fill: a solid badge, a button.

--magma-warning-emphasis-hover

bg-warning-emphasis-hover

#715500

alias of --status-warning-03

#ffd559

The solid warning fill, hovered.

--magma-warning-emphasis-active

bg-warning-emphasis-active

#584200

alias of --status-warning-02

#ffe595

The solid warning fill, pressed.

--magma-warning-on-emphasis

text-warning-on-emphasis

#ffffff

alias of --tone-neutral-seed

#1d1d1d

Text and icons on the solid warning fill.

--magma-warning-surface

bg-warning-surface

#ffdc75

alias of --status-warning-09

#6b5000

Shortcut for the warning background at its default prominence (wash-base).

--magma-warning-fg

text-warning-fg

#3a2c00

alias of --text-warning-default

#fff2cd

Shortcut for the default warning text (text-default).

--magma-warning-border

border-warning-border

#e2bf75

alias of --border-warning-default

#9b6200

Shortcut for the functional warning border (border-default).

Danger

--magma-danger-wash-soft

bg-danger-wash-soft

#ffe8e6

alias of --status-error-10

#770000

The danger background, the least marked.

--magma-danger-wash-base

bg-danger-wash-base

#ffd6d3

alias of --status-error-09

#9e1823

The danger background, at its default prominence.

--magma-danger-wash-strong

bg-danger-wash-strong

#fec6c2

alias of --status-error-08

#b63236

The danger background, the most marked: icons only, no essential text.

--magma-danger-text-default

text-danger-fg-default

#590000

alias of --text-error-default

#ffefee

Danger text on the danger background.

--magma-danger-text-muted

text-danger-fg-muted

#84000b

alias of --text-error-muted

#ffdfdd

Secondary danger text on the danger background.

--magma-danger-text-subtle

text-danger-fg-subtle

#a52128

alias of --text-error-subtle

#ffceca

Non-essential danger text on the danger background.

--magma-danger-text-disabled

text-danger-fg-disabled

#d95352

alias of --text-error-disabled

#faa5a0

Disabled danger text on the danger background.

--magma-danger-border-muted

border-danger-border-muted

#ffcbc6

alias of --border-error-muted

#7e000f

The decorative danger border.

--magma-danger-border-default

border-danger-border-default

#feaba5

alias of --border-error-default

#bc3a3c

The functional danger border.

--magma-danger-border-strong

border-danger-border-strong

#da605d

alias of --border-error-strong

#f18883

The danger border that conveys a state.

--magma-danger-emphasis

bg-danger-emphasis

#c44041

alias of --status-error-04

#fdb8b2

The solid danger fill: a solid badge, a button.

--magma-danger-emphasis-hover

bg-danger-emphasis-hover

#a52128

alias of --status-error-03

#ffceca

The solid danger fill, hovered.

--magma-danger-emphasis-active

bg-danger-emphasis-active

#84000b

alias of --status-error-02

#ffdfdd

The solid danger fill, pressed.

--magma-danger-on-emphasis

text-danger-on-emphasis

#ffffff

alias of --tone-neutral-seed

#1d1d1d

Text and icons on the solid danger fill.

--magma-danger-surface

bg-danger-surface

#ffd6d3

alias of --status-error-09

#9e1823

Shortcut for the danger background at its default prominence (wash-base).

--magma-danger-fg

text-danger-fg

#590000

alias of --text-error-default

#ffefee

Shortcut for the default danger text (text-default).

--magma-danger-border

border-danger-border

#feaba5

alias of --border-error-default

#bc3a3c

Shortcut for the functional danger border (border-default).

Pairing rules

-fg on a neutral surface, -on-emphasis on the fill.

Text on a wash is bounded: wash-soft takes the whole text ladder, wash-base only text-default, wash-strong icons only. The same holds for every status.

Hierarchy without losing contrast: use weight, size and spacing, and soften the chrome (border-muted, zebra on surface-muted) rather than the text.

Elevation is a role: page surface-default, card surface-raised, floating layer surface-overlay, well surface-sunken. A grey that has to look marked in both modes is a wash, not a surface.

These are the pairs Magma measures for contrast; any other combination is not measured.

Palettes

The primitives the roles point at, from 01 to 10. Paint with them only when the color is data: a category, a tag, a color the user picked (label-*), a brand (brand-*). The strips follow the mode of this page; a click on a swatch copies its custom property.

Tones

The neutral families. neutral is the grey of the default theme; porcelain and bisque back the cool and warm themes: switch those on with data-theme-name, do not paint with them by hand. seed is the paper of the mode, white in light and black in dark.

porcelain

seed

kaolin

seed

neutral

seed

fireclay

seed

bisque

seed

Status colors

--status-info

#23b2e1

base

--status-success

#21bf73

base

--status-error

#ed6663

base

--status-warning

#ffc107

base

Labels

--label-red

#d01b1b

base

--label-amaranth

#f43f5e

base

--label-orchid

#ec4899

base

--label-purple

#a855f7

base

--label-violet

#8b5cf6

base

--label-blue

#0e36f6

base

--label-sky

#0ea5e9

base

--label-aqua

#06b6d4

base

--label-green

#22c55e

base

--label-lime

#84cc16

base

--label-yellow

#eab308

base

--label-orange

#f97316

base

Brands

--brand-maggioli

#00379e

base

--brand-maggioli-editore

#0f4ad5

base

--brand-rnd

#cba26b

base

Variants

Aliases of the families they name, kept for the variant prop of the components. They have no role of their own: the accents are accent and accent-ai.

--variant-primary

alias of --brand-maggioli

base

--variant-secondary

alias of --brand-maggioli-editore

base

--variant-ai

alias of --label-violet

base

Role primitives

The steps behind the neutral and status roles, one set per family. They follow the mode but not the named theme nor the contrast preference: paint with the --magma-* roles.

--surface-<family>-sunken

--surface-<family>-muted

--surface-<family>-default

--surface-<family>-raised

--surface-<family>-overlay

--border-<family>-muted

--border-<family>-default

--border-<family>-strong

--text-<family>-default

--text-<family>-muted

--text-<family>-subtle

--text-<family>-disabled