Themes and utilities

PAM Mobile UI resolves themes and utility classes in PHP before encoding the native element tree. Android receives numeric colors, dimensions, and native properties rather than CSS.

System theme

The mobile-ui project preset enables the system theme. Provider subtrees can resolve light, dark, or system mode independently.

Override semantic tokens

use Pam\MobileUi\Enum\ColorToken;
use Pam\MobileUi\PamUI;
use Pam\MobileUi\Theme\Color;
use Pam\MobileUi\Theme\Themes;

PamUI::theme(
    Themes::light()->withColors([
        ColorToken::Primary->value =>
            Color::rgb(37, 99, 235),
    ]),
    Themes::dark()->withColors([
        ColorToken::Primary->value =>
            Color::rgb(147, 197, 253),
    ]),
);

Override semantic application tokens instead of hard-coding a raw color into every component.

Token behavior

Tokens are integer-backed enum values. The theme resolver maps them to concrete colors for the active provider subtree.

This keeps:

• light and dark behavior explicit;
• component recipes reusable;
• native payloads compact;
• coded fields stable across PHP and Android; and
• application overrides separate from component implementation.

Utility classes

Declarative classes cover layout, spacing, typography, colors, borders, radius, elevation, transforms, visibility, and supported state paths.

<Card class="p-6 gap-4 rounded-xl ui-bg">
    <Heading class="text-primary">Account</Heading>
    <Text class="text-muted">Manage your preferences.</Text>
</Card>

Classes resolve through a versioned registry. A selected recipe utility without a packed native implementation fails the recipe test rather than silently disappearing.

Component recipes

Generated recipes combine:

• size and variant axes;
• compound rules;
• active, checked, disabled, focused, hovered, invalid, selected, and flipped states;
• light and dark themes; and
• component subparts.

Run:

composer test:recipes

The test expands every generated facade through captured variants and supported states.

Raw style escape hatch

Typed components can still receive a PAM Native Style:

$card->style(
    new Style(
        padding: 24.0,
        gap: 16.0,
        borderRadius: 20.0,
    ),
);

Use raw styles for application-specific layout or a value not represented by a Mobile UI recipe. Prefer theme tokens for reusable semantic color.

Accessibility

Theme customization must preserve:

• readable contrast;
• visible focus and selected state;
• disabled and invalid semantics that are not color-only;
• touch target size; and
• text scaling without clipping.

Component verification records accessibility separately from theme coverage. Passing one gate does not imply the other.