pragma_design_system 1.0.2

Flutter library that gathers Pragma's design tokens, themes, and base components for mobile apps.

pragma_design_system

Flutter library focused on mobile experiences that bundles Pragma's design tokens, base themes, and reusable UI components.

Features

• Consistent color, typography, spacing, and responsive grid tokens.
• PragmaTheme with light/dark variants and Material 3 enabled by default.
• Accessible components (PragmaButton, PragmaCard, PragmaIconButtonWidget, PragmaInputWidget, PragmaToastWidget, PragmaAccordionWidget, PragmaColorTokenRowWidget, PragmaThemeEditorWidget, PragmaLogoWidget).
• Theme lab sample that lets you edit colors/typography in real time and export a JSON payload backed by ModelThemePragma.
• PragmaGridTokens, viewport helpers, and the PragmaGridContainer widget to debug layouts.
• Component modeling (ModelPragmaComponent, ModelAnatomyAttribute) to sync documentation and showcases from JSON.
• Example app ready to run and validate (includes a "Grid debugger" page).

Installation

Add the package to your pubspec.yaml:

dependencies:
	pragma_design_system: ^1.0.2

Then run:

flutter pub get

Quick start

import 'package:flutter/material.dart';
import 'package:pragma_design_system/pragma_design_system.dart';

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

	@override
	Widget build(BuildContext context) {
		return MaterialApp(
			title: 'Pragma Design System',
			theme: PragmaTheme.light(),
			darkTheme: PragmaTheme.dark(),
			home: const PragmaHome(),
		);
	}
}

Tokens and components

• Colors: PragmaColors exposes brand-aware ColorScheme definitions for light and dark modes.
• Typography: PragmaTypography defines responsive scales built on top of Google Fonts.
• Spacing: PragmaSpacing concentrates 4pt-system values and handy utilities.
• Radius: PragmaBorderRadiusTokens and PragmaBorderRadius keep rounded corners consistent in 4/8dp steps.
• Rounded-corner guidance lives in doc/rounded_corners.md, covering increments, implementation, and heuristics per component size.
• Opacity: PragmaOpacityTokens and PragmaOpacity constrain overlays to 8/30/60 intervals using Color.withValues for Flutter 3.22+.
• Domain models: ModelPragmaComponent, ModelAnatomyAttribute, ModelFieldState, ModelColorToken, and ModelThemePragma serialize the documentation sourced from Figma, power the input widgets, and guarantee JSON roundtrips.
• Grid: PragmaGridTokens, getGridConfigFromContext, PragmaGridContainer, and PragmaScaleBox help replicate the official grid, respect gutters, and scale full mockups.
• Components: Widgets such as PragmaPrimaryButton, PragmaSecondaryButton, PragmaButton.icon, PragmaCard, PragmaCardWidget, PragmaDropdownWidget, PragmaInputWidget, PragmaToastWidget, PragmaAvatarWidget, PragmaBreadcrumbWidget, PragmaAccordionWidget, PragmaColorTokenRowWidget, PragmaThemeEditorWidget, or PragmaLogoWidget ship consistent states and elevation.

Avatar quick sample

PragmaAvatarWidget(
	radius: 28,
	initials: 'PD',
	imageUrl: 'https://cdn.pragma.co/avatar.jpg',
	style: PragmaAvatarStyle.primary,
	tooltip: 'Pragma Designer',
)

Button quick sample

PragmaPrimaryButton(
	label: 'Guardar cambios',
	one: PragmaButtonTone.brand,
	onPressed: () {},
)

PragmaButton.icon(
	label: 'Ver detalles',
	icon: Icons.open_in_new,
	hierarchy: PragmaButtonHierarchy.tertiary,
	onPressed: () {},
)

Icon button quick sample

PragmaIconButtonWidget(
	icon: Icons.add,
	style: PragmaIconButtonStyle.filledLight,
	onPressed: () {},
)

PragmaIconButtonWidget(
	icon: Icons.close,
	style: PragmaIconButtonStyle.outlinedDark,
	size: PragmaIconButtonSize.compact,
	onPressed: () {},
)

Input quick sample

final PragmaInputController controller = PragmaInputController(
	ModelFieldState(
		suggestions: <String>['Discovery Lab', 'Growth', 'Mobile Core'],
	),
);

PragmaInputWidget(
	label: 'Nombre del squad',
	controller: controller,
	placeholder: 'Escribe un equipo',
	helperText: 'Filtramos sugerencias automáticamente',
	enablePasswordToggle: true,
	obscureText: true,
	onChanged: (String value) {
		controller
			..setValidation(isDirty: true, isValid: value.isNotEmpty)
			..setError(value.isEmpty ? 'Dato requerido' : null);
	},
);

Color token row quick sample

ModelColorToken token = ModelColorToken(
	label: 'Primary',
	color: '#6750A4',
);

PragmaColorTokenRowWidget(
	token: token,
	onChanged: (ModelColorToken updated) {
		token = updated;
	},
);

Logo quick sample

PragmaLogoWidget(
	width: 200,
	variant: PragmaLogoVariant.wordmark,
);

PragmaLogoWidget(
	width: 96,
	variant: PragmaLogoVariant.isotypeCircle,
);

Theme editor quick sample

ModelThemePragma theme = ModelThemePragma();

PragmaThemeEditorWidget(
	theme: theme,
	onChanged: (ModelThemePragma updated) {
		theme = updated;
		final ThemeData data = PragmaThemeBuilder.buildTheme(updated);
		// Usa [data] para recargar tu MaterialApp o persistir el JSON generado.
	},
);

Theme Lab workflow

1. Ejecuta el example/ y presiona el botón Theme lab del AppBar (junto al Grid debugger) para abrir la página dedicada.
2. Ajusta la tipografía, el modo (claro/oscuro) y cada ModelColorToken desde los PragmaColorTokenRowWidget dentro del panel izquierdo.
3. Observa los cambios en vivo en el panel derecho: los botones, tarjetas (PragmaCardWidget) y gradientes usan el ThemeData generado por PragmaThemeBuilder.
4. Copia el JSON resultante desde la sección "JSON listo para exportar" para versionarlo o compartirlo con tu squad.
5. Carga el JSON dentro de tu app (ModelThemePragma.fromJson(payload)) y construye un ThemeData con PragmaThemeBuilder.buildTheme para aplicar el tema en caliente o persistirlo como configuración.

Toast quick sample

PragmaToastService.showToast(
	context: context,
	title: 'Operación exitosa',
	message: 'Synced con Discovery Lab hace 10 segundos.',
	variant: PragmaToastVariant.success,
	duration: const Duration(milliseconds: 4500),
	alignment: PragmaToastAlignment.topRight,
	actionLabel: 'Ver log',
	onActionPressed: () {
		debugPrint('Mostrar detalles');
	},
);

Breadcrumb quick sample

PragmaBreadcrumbWidget(
	items: const <PragmaBreadcrumbItem>[
		PragmaBreadcrumbItem(label: 'Home', onTap: _navigateHome),
		PragmaBreadcrumbItem(label: 'Components', onTap: _goToComponents),
		PragmaBreadcrumbItem(label: 'Breadcrumb', isCurrent: true),
	],
	type: PragmaBreadcrumbType.underline,
)

See doc/opacity_tokens.md for the full opacity table and Color.withValues examples.

Read doc/component_modeling.md to structure JSON payloads and reuse them in showcases.

Explore lib/src for additional utilities, run the example app, and check doc/grid_utilities.md to adopt the grid helpers.

Review doc/logo.md for asset usage guidelines and doc/fonts.md for typography, licensing, and offline distribution tips.

Typography and license

• See doc/fonts.md for the complete typography contract plus license highlights.
• The official typeface is Poppins and PragmaTypography applies it through GoogleFonts.poppins.
• The family ships under the SIL Open Font License 1.1; see the full text in licenses/Poppins-OFL.txt.
• If your app must work offline on first launch, bundle the .ttf files in your assets and disable runtime fetching.
• Follow doc/poppins_offline.md for the step-by-step guide and download links.

How to prepare an offline fallback

1. Download the weights you use (for example Regular, SemiBold, and Bold) from Google Fonts and store them inside assets/fonts/.

2. Declare them in pubspec.yaml:

   flutter:
   	 fonts:
   		 - family: Poppins
   			 fonts:
   				 - asset: assets/fonts/Poppins-Regular.ttf
   				 - asset: assets/fonts/Poppins-SemiBold.ttf
   				 - asset: assets/fonts/Poppins-Bold.ttf
   

3. Disable runtime fetching during startup:

   void main() {
   	 GoogleFonts.config.allowRuntimeFetching = false;
   	 runApp(const PragmaApp());
   }
   

   Remember to import package:google_fonts/google_fonts.dart.

If you skip bundling the files, the responsibility of providing the typeface falls on the app that consumes this package.

Example

cd example
flutter run

The sample app toggles themes, tokens, and staple components.

Development

Card quick sample

PragmaCardWidget(
	title: 'Funnel weekly',
	subtitle: 'Actualizado hace 5 min',
	body: Column(
		crossAxisAlignment: CrossAxisAlignment.start,
		children: const <Widget>[
			Text('Sesiones: 18.4K'),
			SizedBox(height: PragmaSpacing.xs),
			Text('CTR: 4.1% vs semana anterior'),
		],
	),
	variant: PragmaCardVariant.tonal,
	actions: <Widget>[
		PragmaButton.icon(
			label: 'Ver dashboard',
			icon: Icons.open_in_new,
			hierarchy: PragmaButtonHierarchy.tertiary,
			onPressed: () {},
		),
	],
)

Dropdown quick sample

PragmaDropdownWidget<String>(
	label: 'Rol asignado',
	placeholder: 'Selecciona un rol',
	helperText: 'Usaremos este rol en los tableros',
	options: const <PragmaDropdownOption<String>>[
		PragmaDropdownOption(label: 'Product Designer', value: 'ux'),
		PragmaDropdownOption(label: 'Product Manager', value: 'pm'),
		PragmaDropdownOption(label: 'iOS Engineer', value: 'ios'),
	],
	onChanged: (String? value) {
		debugPrint('Role: $value');
	},
)

• flutter test to run the tests.

Dropdown list quick sample

PragmaDropdownListWidget<String>(
	label: 'Equipo colaborador',
	placeholder: 'Selecciona perfiles',
	options: const <PragmaDropdownOption<String>>[
		PragmaDropdownOption(label: 'UX Research', value: 'research'),
		PragmaDropdownOption(label: 'Mobile iOS', value: 'ios'),
		PragmaDropdownOption(label: 'Mobile Android', value: 'android'),
	],
	initialSelectedValues: const <String>['ios'],
	onSelectionChanged: (List<String> roles) {
		debugPrint('Seleccionados: $roles');
	},
	onItemRemoved: (String value) {
		debugPrint('Eliminado: $value');
	},
)
- `dart format .` to keep formatting consistent.
- `flutter analyze` to validate against `analysis_options.yaml`.