LayrzCard

LayrzCard

A simple, minimal container shell with elevation and hover behaviour for wrapping display content. Specification status: brand-new component, not yet confirmed by the team. Parameters listed below are confirmed; several candidates for future parameters are noted as Open Questions.

Metadata
Status: Emerging (specification not finalized)
Phase: M2 (Core primitives)
Domain: Display
Primitive: Hand-rolled (no Material Card, InkWell, or equivalents outside widgets)

---

Overview

LayrzCard is a foundational shell component intended to wrap other display components (table rows, list items, dialog surfaces). It applies elevation and shadow treatment from the M1 design token layer and provides a consistent hover interaction state. Because it serves as the visual language for all surfaces in the system, its elevation and interaction behaviour matter disproportionately to its simplicity.

Design Principles

• Simple shell: A container for child content; elevation and shadow only.
• Elevation and shadows from tokens: Resolved from the M1 elevation and shadow system (see Design Tokens link below), not hardcoded.
• Hover feedback: Stateful visual affordance on desktop platforms via the M1 WidgetState resolution layer.
• Optional tap handler: Tap interaction is optional; see Open Questions for how the visual treatment changes when onTap is null.
• No Material Card or InkWell: All hover and press handling is hand-rolled on WidgetState/WidgetStatesController.

---

API Structure (Confirmed Parameters)

Core Constructor

// Design sketch — illustrative only
class LayrzCard extends StatelessWidget {
  /// The widget displayed inside the card.
  final Widget child;

  /// Elevation level, resolved from the elevation and shadow tokens.
  ///
  /// Must reference the M1 token system rather than being hardcoded.
  /// See: https://github.com/goldenm-software/layrz_ui/blob/main/engineering/design-tokens.md
  final double elevation;

  /// Callback invoked when the card is tapped.
  ///
  /// If null, the card is not interactive.
  /// See Open Questions for hover behaviour when this is null.
  final VoidCallback? onTap;

  // Constructor omitted for brevity
}

---

Dependencies

• M1 Elevation and Shadow Tokens — Must resolve elevation from the token system, not accept arbitrary values.
• M1 WidgetState Resolution Layer — For hover and press state tracking without Material.
• No Material imports — All interaction affordances are hand-rolled.

---

Open Questions

The following parameters and behaviours have NOT been confirmed by the team and are candidates for future API evolution:

• Padding and margin: Does the card add internal padding, or does the caller wrap the child in padding?
• Background colour override: Should there be a backgroundColor parameter to override the default theme surface colour?
• Border: Should the card support an optional border (stroke, style, width)?
• Border radius: Is there a fixed border radius, or should it be configurable?
• Additional interactions: Besides onTap, should onLongPress, onSecondaryTap, and/or onHover callbacks be supported?
• Hover visual treatment: What happens when onTap is null? Does the card still show hover feedback, or is it disabled?
• Disabled state: Should there be an isDisabled parameter to prevent interaction independently of onTap?
• Tap feedback visual: When tapped or hovered, should the card shift elevation, change opacity, or apply another effect?

---

Why This Matters

LayrzCard is a shell that will become the foundation for:

• Table rows and cells.
• List items and grouped lists.
• Dialog and modal surfaces.
• Menu items and dropdowns.
• Card grids and dashboard tiles.

Its elevation and hover treatment set the precedent for the entire system's surface language. Early alignment with design tokens and WidgetState resolution ensures consistency and avoids rework downstream.

---

Last updated: 2026-08-13
Related documents: Design Tokens, Architecture, Roadmap