SGDS Color Token Suffix Semantics

Shared reference for suffix modifiers used consistently across all SGDS color utilities — background, border, and text.

Semantic Color Categories

All color utilities share the same set of semantic category names:

Category	Meaning
primary	Brand color — emphasis, identity
accent	Informational / links — neutral, no urgency
success	Positive feedback, completion
danger	Errors, destructive actions
warning	Caution, needs attention
purple	Visual variety — no semantic meaning
cyan	Visual variety — no semantic meaning
neutral	Equal importance — no differentiation

Purple and Cyan are non-semantic alternatives used for visual variety. Use them when primary and accent colors are similar and you need a third distinguishable color, or when you want alternating colors without implying priority.

Emphasis Modifiers

Applied to all semantic color tokens (primary, accent, success, danger, warning, purple, cyan, neutral):

default

Balanced, standard appearance — the baseline.

• Use for typical states and common-frequency elements
• Neither draws maximum attention nor recedes into the background

emphasis

Strong, high-visibility appearance.

• Use when the element must draw attention
• Maximum saturation/contrast within the color family
• For active states, call-to-action indicators, high-priority signals

muted

Reduced, subtle appearance.

• Use when color should be present but not dominate
• Lower saturation or lighter tint
• For secondary information, inactive states, or low-priority indicators

Emphasis progression (weakest → strongest):

muted → default → emphasis

Theme Behavior Modifiers

fixed-light

Always light — never changes with theme mode.

• The color is locked to its light-mode value regardless of the user's current theme (day or night)
• Use when a specific region must always appear on a light surface — e.g., a section with a background image that requires light borders or text

fixed-dark

Always dark — never changes with theme mode.

• The color is locked to its dark-mode value regardless of theme
• Use for regions that must always appear dark — e.g., a footer or hero that never inverts

inverse

Opposite of the current theme.

• In light (day) mode → renders as dark
• In dark (night) mode → renders as light
• Use for high-contrast elements that should visually stand out from the surrounding theme background

Transparency Modifiers

translucent

Semi-transparent — allows underlying content to show through.

• Use for hover/active state overlays on buttons or interactive elements
• Use on elements layered over images or gradients where full opacity would look harsh

transparent

Fully invisible — no visible color, but the element still occupies space.

• Use for outline-style components that need consistent sizing with their filled variants
• Maintains box model without rendering any color

Background-Specific Modifiers

These modifiers exist only in background-color tokens:

alternate

Second page-level background for creating visual rhythm.

• Alternate between default and alternate across page sections to create clear visual separation
• Neither value is "primary" — they are equals used for alternation

overlay

Full-screen backdrop — never use on components.

• Exclusively for modal, drawer, and dialog backdrops
• Should always span the full viewport

surface

Component-level scope — the key distinction from page-level tokens.

• Background tokens containing surface → scoped to components (cards, badges, panels, inputs)
• Background tokens without surface → scoped to page sections (body, section, full-width areas)
• Border and text tokens do not use surface — they apply at component/container level only

Background level summary:

Token pattern	Scope
sgds:bg-{color}-default	Page level
sgds:bg-{color}-surface-default	Component level
sgds:bg-surface-default	Component (foundational, no semantic color)

Quick Reference

Modifier	Meaning	Changes with theme?
default	Standard	✅ Yes
emphasis	Strong	✅ Yes
muted	Subtle	✅ Yes
fixed-light	Always light	❌ No
fixed-dark	Always dark	❌ No
inverse	Opposite theme	✅ Yes (inverted)
translucent	Semi-transparent	✅ Yes
transparent	Invisible	N/A
alternate	Section rhythm (bg only)	✅ Yes
overlay	Full-screen backdrop (bg only)	✅ Yes
surface	Component scope (bg only)	✅ Yes

See Also

• utilities-background-color — Background color utilities
• utilities-border-color — Border color, width, and radius utilities
• utilities-text-color — Text color utilities