Getting Started

Getting Started

layrz_ui is a Material-free, Cupertino-free Flutter design system built exclusively on package:flutter/widgets.dart and dart:ui. This guide walks you through adding layrz_ui to your app and building your first screen.

---

Add the Dependency

layrz_ui is not yet published to pub.dev. Install it from the GitHub repository as a git dependency in your pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  layrz_ui:
    git:
      url: git@github.com:goldenm-software/layrz_ui.git
      ref: main

If you do not have SSH access to GitHub, use the HTTPS URL instead:

  layrz_ui:
    git:
      url: https://github.com/goldenm-software/layrz_ui.git
      ref: main

Then run flutter pub get.

Note: layrz_ui is currently in development and not available on pub.dev. This section will be updated when publication happens. For now, use the git dependency above. Pin the main branch (the stable/release branch), not development (active development).

---

The Minimal App

Every layrz_ui app must wrap its content in a LayrzApp or LayrzApp.router widget. This installs the theme system, text styles, and default icon rendering.

Imperative Routing

Use LayrzApp with a home screen for simple apps:

import 'package:flutter/widgets.dart';
import 'package:layrz_ui/layrz_ui.dart';

void main() {
  runApp(const MyApp());
}

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

  @override
  Widget build(BuildContext context) {
    return LayrzApp(
      title: 'My App',
      theme: LayrzThemeData.light(),
      home: const HomePage(),
    );
  }
}

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

  @override
  Widget build(BuildContext context) {
    return Container(
      color: context.theme.backgroundColor,
      child: Center(
        child: Text(
          'Hello, layrz_ui!',
          style: context.theme.textStyle,
        ),
      ),
    );
  }
}

Declarative Routing (go_router, auto_route, etc.)

For apps using a declarative router like go_router, use LayrzApp.router:

import 'package:go_router/go_router.dart';
import 'package:flutter/widgets.dart';
import 'package:layrz_ui/layrz_ui.dart';

final _router = GoRouter(
  routes: [
    GoRoute(path: '/', builder: (_, __) => const HomePage()),
  ],
);

void main() {
  runApp(const MyApp());
}

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

  @override
  Widget build(BuildContext context) {
    return LayrzApp.router(
      title: 'My App',
      theme: LayrzThemeData.light(),
      routerConfig: _router,
    );
  }
}

---

Font Setup

layrz_ui ships with Open Sans (from Google Fonts) as the default font. To use it, you must preload it in your main() function before calling runApp().

Why Preload?

If you skip font preloading, text will render in a system fallback font until Open Sans loads from Google Fonts. This causes a visual flash and layout shift. Preloading avoids this.

Preload Open Sans

import 'package:flutter/widgets.dart';
import 'package:layrz_ui/layrz_ui.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Preload the default Layrz font (Open Sans)
  const handler = LayrzGoogleFontsHandler();
  try {
    await handler.preload(kLayrzFont);
  } catch (e) {
    // Gracefully degrade if preload fails (e.g., no internet)
    debugPrint('Font preload failed: $e');
  }

  runApp(const MyApp());
}

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

  @override
  Widget build(BuildContext context) {
    return LayrzApp(
      title: 'My App',
      theme: LayrzThemeData.light(
        fontHandler: const LayrzGoogleFontsHandler(),
      ),
      home: const HomePage(),
    );
  }
}

Key points:

• Call WidgetsFlutterBinding.ensureInitialized() before any async work in main().
• Wrap preload in a try/catch — if the device is offline, preload will fail, but your app degrades gracefully with fallback fonts.
• Pass the same LayrzGoogleFontsHandler to LayrzThemeData.light() so typography uses the preloaded font.

---

Reading Theme Values in a Widget

Once LayrzApp is installed, every widget in the tree can access the theme via context. Three extension methods are available on BuildContext:

Extension	Returns	What it does
context.theme	LayrzThemeData	Access the full theme (colors, typography, all tokens)
context.tokens	LayrzTokens	Access the token set directly
context.tokenizer	LayrzTokenizer	Access tokens via the facade (shortcuts for common values)

Example: Using Theme Values

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

  @override
  Widget build(BuildContext context) {
    final theme = context.theme;
    final tokenizer = context.tokenizer;

    return Container(
      decoration: BoxDecoration(
        color: theme.backgroundColor,
        borderRadius: BorderRadius.circular(theme.borderRadius),
        boxShadow: theme.tokens.shadow.elevation1,
      ),
      padding: EdgeInsets.all(theme.tokens.spacing.sp3),
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          Text(
            'Card Title',
            style: theme.textTheme.title,
          ),
          const SizedBox(height: 12),
          Text(
            'Card body text.',
            style: theme.textStyle,
          ),
        ],
      ),
    );
  }
}

The three access patterns are equivalent but suit different code styles:

• context.theme.tokens.colors.primary — most explicit, reads all the way down
• context.tokens.colors.primary — shorter, still explicit
• context.tokenizer.primary — shortest, uses a flat shortcut; best for common values

See LayrzTokenizer for all available shortcuts.

---

Your First Screen

Here is a complete, working first screen that uses layrz_ui:

import 'package:flutter/widgets.dart';
import 'package:layrz_ui/layrz_ui.dart';

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

  @override
  Widget build(BuildContext context) {
    final theme = context.theme;

    return Container(
      color: theme.backgroundColor,
      child: SingleChildScrollView(
        child: Padding(
          padding: EdgeInsets.all(theme.tokens.spacing.sp4),
          child: Column(
            crossAxisAlignment: CrossAxisAlignment.start,
            children: [
              Text(
                'Welcome to layrz_ui',
                style: theme.textTheme.display,
              ),
              const SizedBox(height: 24),
              Container(
                decoration: BoxDecoration(
                  color: theme.surfaceColor,
                  borderRadius: BorderRadius.circular(theme.borderRadius),
                  boxShadow: theme.tokens.shadow.elevation2,
                ),
                padding: EdgeInsets.all(theme.tokens.spacing.sp4),
                child: Column(
                  crossAxisAlignment: CrossAxisAlignment.start,
                  children: [
                    Text(
                      'This is a surface with elevation 2',
                      style: theme.textTheme.body,
                    ),
                    const SizedBox(height: 12),
                    Text(
                      'Design tokens make styling consistent and maintainable.',
                      style: theme.textStyle.copyWith(
                        color: theme.hintColor,
                      ),
                    ),
                  ],
                ),
              ),
            ],
          ),
        ),
      ),
    );
  }
}

---

What layrz_ui Is Not

• No Material — layrz_ui does not import package:flutter/material.dart. This means no Material icons, no Material-specific widgets, and no Material color schemes.
• No Cupertino — no iOS-specific component library. layrz_ui uses widgets generic to all platforms.
• Light Mode Only — layrz_ui targets light mode only. Dark mode is out of scope. See decision D7 for the rationale.

---

Next Steps

• Explore the theme system: Read Theming to understand how the theme works and how to customize it.
• Access design tokens: Read Design-Tokens for the complete reference of colors, spacing, radius, shadows, and other tokens.
• Use the tokenizer facade: Read LayrzTokenizer for shortcuts to common token values.
• Set up custom fonts: Read Fonts to use fonts other than Open Sans or load fonts from custom URIs.
• Browse components: See the Component Catalog for the list of all available widgets.

---

Last updated: 2026-08-13
Related pages: Theming, Design-Tokens, Fonts, LayrzApp