Status

Status is a core concept in Reef that provides semantic color theming across components. It defines a set of predefined status values that convey meaning through color, helping users understand the nature and importance of UI elements at a glance.

Overview

The Status type is defined as a union of string literals, each representing a semantic color category:

export type Status =
  | "success"
  | "danger"
  | "warning"
  | "info"
  | "neutral"
  | "primary"
  | "secondary"
  | "background";

Each status value maps to a color palette in the theme system, providing consistent visual feedback throughout your application.

Status Values

Below are all available status values with their typical use cases:

Status	Use Case
`success`	Positive actions, confirmations, completed states
`danger`	Errors, destructive actions, warnings that need attention
`warning`	Caution states, pending actions, alerts
`info`	Informational content, tips, neutral highlights
`neutral`	Default state, no semantic meaning
`primary`	Primary brand color, main actions
`secondary`	Secondary brand color, alternative actions
`background`	Background-based theming, blends with page background

Visual Examples

Containers

The Container component uses status to determine its background and border colors:

success

danger

warning

info

neutral

primary

secondary

background

Buttons

Buttons accept a status prop to change their color scheme:

Text

The Text component can display different status colors:

Success text

Danger text

Warning text

Info text

Neutral text

Primary text

Secondary text

Usage

Importing the Type

Import the Status type from the Reef package for type-safe usage:

import type { Status } from "@228-co/reef/status";

// Use in your component props
interface MyComponentProps {
  status?: Status;
}

Using Status with Components

Most Reef components accept an optional status prop:

import { Button, Container, Text } from "@228-co/reef/components";

// Button with status
<Button status="success" label="Save" />
<Button status="danger" label="Delete" />

// Container with status
<Container status="warning">
  <Text>This is a warning message</Text>
</Container>

// Text with status
<Text status="info">Information text</Text>

Context Inheritance

Components inside a Container automatically inherit its status through the ContainerContext. This enables consistent theming without explicitly passing status to every child:

This text inherits the danger status

<Container status="danger">
  {/* Text inherits "danger" from Container */}
  <Text>This text inherits the danger status</Text>
  
  {/* Button inherits "danger" from Container */}
  <Button label="Inherited" />
  
  {/* Explicit status overrides inheritance */}
  <Button status="success" label="Overridden" />
</Container>

Status and Depth

Status colors work in conjunction with the depth system. Each status has 9 color levels (100-900) that create visual hierarchy through varying brightness:

Primary depth 1 (darkest)

Primary depth 3

Primary depth 5 (medium)

Primary depth 7

Primary depth 9 (lightest)

Nested containers automatically adjust depth to create visual layering:

Outer container (depth 6)

Inner container (depth 7)

Deepest container (depth 8)

Theme Integration

Status colors are defined in the theme system through StyleX theme variables. Each status maps to a set of color tokens in the themeColors object:

// Theme colors follow the pattern: {status}{depth}
// e.g., success100, success500, danger300, primary900

// Components access colors dynamically:
themeColors[`${status}${depth * 100}`]

// Example: status="danger" with depth=5
// Results in: themeColors.danger500

This pattern enables consistent color application across all components while supporting both light and dark mode through CSS media queries.

Default Values

Components have sensible defaults when no status is provided:

Container - Defaults to "background"

Button - Uses container status if inside a Container, otherwise "neutral"

Text - Inherits from ContainerContext if available

Best Practices

Use semantic status values - Choose status based on meaning, not just color preference

Leverage context inheritance - Wrap related elements in a Container to share status

Reserve danger for destructive actions - Use for delete buttons, error messages, and critical warnings

Use success sparingly - Reserve for confirmations and completed states

Prefer primary for main CTAs - Your primary brand action should use the primary status

Test with color blindness simulators - Ensure status is conveyed through more than just color