LayrzTokenizer

LayrzTokenizer

A convenience facade providing semantic access to design tokens via both group getters and flat shortcuts.

---

Overview

LayrzTokenizer wraps a LayrzTokens object and provides two access patterns:

1. Group getters — access all tokens of a category at once (e.g., all colors)
2. Flat shortcuts — access common single-value patterns quickly (e.g., primary color only)

This dual interface accommodates both detailed component styling (group getters) and quick convenience patterns (flat shortcuts).

---

Access Patterns

Via BuildContext (Recommended)

// Recommended: uses the active theme
final tokenizer = context.tokenizer;
final primary = tokenizer.primary;
final spacing = tokenizer.spacing;

// Direct access to groups
final colors = tokenizer.colors;
final allSpacing = tokenizer.spacingTokens; // Not "spacing" — that's the base unit

Direct Construction

final tokenizer = LayrzTokenizer(context.tokens);
final primary = tokenizer.primary;

Static Access

// Throws if no LayrzTheme is found
final tokenizer = LayrzTokenizer.of(context);

// Returns null if no LayrzTheme is found
final tokenizer = LayrzTokenizer.maybeOf(context);

---

Group Getters

Group getters return the complete token category objects. They are named to avoid collision with flat shortcuts (see naming note below).

Getter	Returns	Access Pattern
colors	LayrzColorTokens	tokenizer.colors.primary
typography	LayrzTextTheme	tokenizer.typography.body
spacingTokens	LayrzSpacingTokens	tokenizer.spacingTokens.sp3 (16 pixels)
radiusTokens	LayrzRadiusTokens	tokenizer.radiusTokens.r3 (16 pixels)
shadowTokens	LayrzShadowTokens	tokenizer.shadowTokens.elevation2
border	LayrzBorderTokens	tokenizer.border.normal
motion	LayrzMotionTokens	tokenizer.motion.dTransition

Why "spacingTokens" and "radiusTokens"?

These group getters are named to provide clear semantics:

• tokenizer.spacingTokens — the full set (use for specific levels like sp1, sp2, etc.)
• tokenizer.radiusTokens — the full set (use for specific levels like r1, r2, etc.)

Flat shortcuts for base units (spacing, radius) and convenience methods were removed in the token refactor to enforce the five-level model. Use the group getters directly: tokenizer.spacingTokens.sp2 for the 8-pixel spacing, tokenizer.radiusTokens.br2 for 8-pixel rounded corners.

---

Flat Shortcuts for Color Tokens

Quick access to semantic colors without drilling into the full color token set.

Shortcut	Returns	Equivalent
primary	Color	tokens.colors.primary
success	Color	tokens.colors.success
warning	Color	tokens.colors.warning
danger	Color	tokens.colors.danger
info	Color	tokens.colors.info
contextual	Color	tokens.colors.contextual
tonalOpacity	double	tokens.colors.tonalOpacity

Example:

Container(
  color: context.tokenizer.primary, // Deep navy blue
)

Text(
  'Error',
  style: TextStyle(color: context.tokenizer.danger),
)

---

Flat Shortcuts for Spacing Tokens

Flat shortcuts provide quick, semantically named access to base spacing values and their derived EdgeInsets:

Shortcut	Returns	Equivalent
spacing	double	tokens.spacing.sp2 (8 logical pixels)
margin	EdgeInsets	tokens.spacing.mg2 (8px on all sides)
reducedMargin	EdgeInsets	tokens.spacing.mg1 (4px on all sides)
padding	EdgeInsets	tokens.spacing.pd2 (8px on all sides)
sizedBox	Widget	SizedBox.square(dimension: 8.0)

For access to all five semantic levels, use the group getter instead:

// Five semantic levels, derived accessors for clarity
context.tokenizer.spacingTokens.sp2    // 8 logical pixels
context.tokenizer.spacingTokens.sp3    // 16 logical pixels
context.tokenizer.spacingTokens.pd2    // EdgeInsets.all(8) — for padding clarity
context.tokenizer.spacingTokens.mg3    // EdgeInsets.all(16) — for margin clarity

Example:

// Use shortcuts for common spacing
Padding(
  padding: context.tokenizer.padding, // EdgeInsets.all(8)
  child: Text('Padded text'),
)

// Or use group getter for specific levels
Padding(
  padding: context.tokenizer.spacingTokens.pd3, // EdgeInsets.all(16)
  child: Text('More spacious'),
)

SizedBox(
  width: context.tokenizer.spacing, // 8 logical pixels
  height: context.tokenizer.spacing,
  child: Loading(),
)

// Reduced margin for nested layouts
Padding(
  padding: context.tokenizer.reducedMargin, // EdgeInsets.all(4)
  child: Text('Compact'),
)

---

Flat Shortcuts for Radius Tokens

Flat shortcuts provide quick, semantically named access to base radius values and their derived BorderRadius:

Shortcut	Returns	Equivalent
radius	double	tokens.radius.r2 (8 logical pixels)
borderRadius	BorderRadius	tokens.radius.br2 (8 logical pixels, all corners)
innerRadius(outerRadius, spacer)	BorderRadius	Computed inner radius for nested borders

For access to all five semantic levels and the pill shape, use the group getter instead:

// Five semantic levels, derived BorderRadius accessors
context.tokenizer.radiusTokens.r2     // 8 logical pixels
context.tokenizer.radiusTokens.r3     // 16 logical pixels
context.tokenizer.radiusTokens.br2    // BorderRadius.circular(8) — derived, for clarity
context.tokenizer.radiusTokens.br3    // BorderRadius.circular(16) — derived, for clarity
context.tokenizer.radiusTokens.full   // 999 (pill shape)

// Nested container math
context.tokenizer.radiusTokens.innerRadius(
  outerRadius: 24.0,
  spacer: 8.0,
) // BorderRadius.circular(16)

Example:

// Use shortcut for common rounded corners
Container(
  decoration: BoxDecoration(
    borderRadius: context.tokenizer.borderRadius,  // 8 pixel radius
    color: Colors.blue,
  ),
)

// Use group getter for specific levels
Container(
  decoration: BoxDecoration(
    borderRadius: context.tokenizer.radiusTokens.br3,  // 16 pixel radius
    color: Colors.blue,
  ),
)

// Nested borders for accent rings
Container(
  decoration: BoxDecoration(
    borderRadius: context.tokenizer.borderRadius,
    color: Colors.blue,
  ),
  padding: EdgeInsets.all(4.0),
  child: Container(
    decoration: BoxDecoration(
      borderRadius: context.tokenizer.innerRadius(
        outerRadius: 8.0,
        spacer: 4.0,
      ),
      color: Colors.white,
    ),
  ),
)

// Pill shape for badges
Container(
  decoration: BoxDecoration(
    borderRadius: BorderRadius.circular(context.tokenizer.radiusTokens.full),
    color: Colors.red,
  ),
)

---

Flat Shortcuts for Shadow Tokens

Quick access to elevation-based shadow decoration generation.

Shortcut	Returns	Equivalent
shadow(...)	BoxDecoration	tokens.shadow.elevation(...)

Example:

Container(
  decoration: context.tokenizer.shadow(elevation: 2),
  // Returns BoxDecoration with shadow, border radius, and surface color
)

// Custom elevation settings
Container(
  decoration: context.tokenizer.shadow(
    elevation: 3,
    radius: 12.0,
    color: Colors.white,
    reverse: false,
  ),
)

See Design-Tokens for complete shadow documentation.

---

Flat Shortcuts for Border Tokens

Quick access to the border base width.

Shortcut	Returns	Equivalent
borderWidth	double	tokens.border.base (1.5)

Example:

Container(
  decoration: BoxDecoration(
    border: Border.all(width: context.tokenizer.borderWidth),
  ),
)

// Or use pre-built border sides
Container(
  decoration: BoxDecoration(
    border: Border(bottom: context.tokens.border.normal),
  ),
)

---

Complete Shortcut Reference

Color Shortcuts (7 total):

• primary, success, warning, danger, info, contextual, tonalOpacity

Spacing Shortcuts (5 total):

• spacing (base unit: sp2, 8px), margin (mg2, 8px), reducedMargin (mg1, 4px), padding (pd2, 8px), sizedBox (8×8 SizedBox)

Radius Shortcuts (3 total):

• radius (base unit: r2, 8px), borderRadius (br2, 8px), innerRadius(outerRadius, spacer) (computed)

Shadow Shortcuts (1 method):

• shadow(...) — elevation-based shadow decoration

Border Shortcuts (1 total):

• borderWidth (base width: 1.5px)

Group Getters (7 total):

• colors, typography, spacingTokens, radiusTokens, shadowTokens, border, motion, breakpointTokens

---

When to Use Each Pattern

Use Flat Shortcuts When:

• Accessing a single, common value (primary color, base spacing)
• Writing quick styling logic where brevity helps readability
• You know the exact value you need (no exploration)

Use Group Getters When:

• Accessing multiple values from the same category
• Building a design system component that needs the full token set
• You want to explore all available values in a category

Use Direct Token Access When:

• You need the lowest-level access
• You're consuming LayrzTokens directly without the facade

Example: Mixed Patterns:

class MyCard extends StatelessWidget {
  const MyCard({super.key});

  @override
  Widget build(BuildContext context) {
    return Container(
      // Use shortcut for single value
      padding: context.tokenizer.padding,
      
      // Use group getter for multiple values
      decoration: BoxDecoration(
        color: context.tokenizer.colors.sf1,
        borderRadius: context.tokenizer.borderRadius,
        boxShadow: context.tokenizer.shadowTokens.elevation2,
      ),
      
      child: Text(
        'Card',
        // Use shortcut for typography base
        style: context.theme.textStyle,
      ),
    );
  }
}

---

Last updated: 2026-08-13
Related pages: Design-Tokens, Theming, Getting-Started